You are on page 1of 208

Distribution Server

Getting Started

Supporting
Distribution Server 7.6

November 2006

Contacting BMC Software


You can access the BMC Software website at http://www.bmc.com. From this website, you can obtain information about the company, its products, corporate offices, special events, and career opportunities.

United States and Canada


Address BMC SOFTWARE INC 2101 CITYWEST BLVD HOUSTON TX 77042-2827 USA Telephone 713 918 8800 or 800 841 2031 Fax 713 918 8000

Outside United States and Canada


Telephone (01) 713 918 8800 Fax (01) 713 918 8000

Copyright 2006 BMC Software, Inc., as an unpublished work. All rights reserved. BMC Software, the BMC Software logos, and all other BMC Software product or service names are registered trademarks or trademarks of BMC Software, Inc. All other trademarks belong to their respective companies. BMC Software considers information included in this documentation to be proprietary and confidential. Your use of this information is subject to the terms and conditions of the applicable End User License Agreement for the product and the proprietary and restricted rights notices included in this documentation.

Restricted rights legend


U.S. Government Restricted Rights to Computer Software. UNPUBLISHED -- RIGHTS RESERVED UNDER THE COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and computer software by the U.S. Government is subject to restrictions, as applicable, set forth in FAR Section 52.227-14, DFARS 252.227-7013, DFARS 252.227-7014, DFARS 252.227-7015, and DFARS 252.227-7025, as amended from time to time. Contractor/Manufacturer is BMC SOFTWARE INC, 2101 CITYWEST BLVD, HOUSTON TX 77042-2827, USA. Any contract notices should be sent to this address.

Customer support
You can obtain technical support by using the BMC Software Customer Support website or by contacting Customer Support by telephone or e-mail. To expedite your inquiry, see Before contacting BMC.

Support website
You can obtain technical support from BMC 24 hours a day, 7 days a week at http://www.bmc.com/support_home. From this website, you can
s s s s s s s

read overviews about support services and programs that BMC offers find the most current information about BMC products search a database for issues similar to yours and possible solutions order or download product documentation report an issue or ask a question subscribe to receive proactive e-mail alerts when new product notices are released find worldwide BMC support center locations and contact information, including e-mail addresses, fax numbers, and telephone numbers

Support by telephone or e-mail


In the United States and Canada, if you need technical support and do not have access to the web, call 800 537 1813 or send an e-mail message to support@bmc.com. Outside the United States and Canada, contact your local support center for assistance.

Before contacting BMC


Have the following information available so that Customer Support can begin working on your issue immediately:
s

product information product name product version (release number) license number and password (trial or permanent)

operating system and environment information machine type operating system type, version, and service pack or other maintenance level such as PUT or PTF system hardware configuration serial numbers related software (database, application, and communication) including type, version, and service pack or maintenance level

s s s

sequence of events leading to the issue commands and options that you used messages received (and the time and date that you received them) product error messages messages from the operating system, such as file system full messages from related software

Distribution Server Getting Started

Contents
Chapter 1 Product components and capabilities 11 12 12 14 15 15 15 16 16 16 17 17 19 21 21 21 23 25 26 26 26 27 27 28 28 28 33 35 36 37 40 44 44 44 47
5

What is the Distribution Server? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Components of the distribution system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Distribution Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Distribution Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Distribution Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Distribution Server Command Line Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Support status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Related documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing online Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing books and release notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Where to go from here. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 2 Installing the Distribution Server

Implementation considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Base installation directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deciding how to install the Distribution Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . Network requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using more than one Distribution Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Choosing a Default or a Custom installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Alternate uses of the Distribution Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Use only the BMC Software installation utility to install the Distribution Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About the installation utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing the Distribution Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Workflow for installing the Distribution Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installable components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Required information for a Default installation of the Distribution Server . . . . . Required information for a Custom installation of the Distribution Server. . . . . Upgrading the Distribution Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Distribution Server installation worksheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing Distribution Server on Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing Distribution Server on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing the Distribution Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Workflow for installing the Distribution Client locally . . . . . . . . . . . . . . . . . . . . . . Required information for a Default, local installation of the Distribution Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Required information for a Custom, local installation of the Distribution Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents

Distribution Client installation worksheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Installing the Distribution Client locally on Windows. . . . . . . . . . . . . . . . . . . . . . . 49 Installing the Distribution Client locally on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . 52 About uninstalling products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Local uninstallation with product CD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Executable file for the uninstallation program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Use the latest version of the uninstallation program . . . . . . . . . . . . . . . . . . . . . . . . 55 Using a CD to uninstall products in a Windows environment. . . . . . . . . . . . . . . . 56 Using a CD to uninstall products in a UNIX environment . . . . . . . . . . . . . . . . . . . 56 Where to go from here . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Chapter 3 Administering and configuring the Distribution Server 59

Setting up accounts and groups for users on the Distribution Server . . . . . . . . . . . . . 61 Starting and stopping programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Starting and stopping the RTserver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Starting and stopping the Distribution Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Starting and stopping the web server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Verifying the installation and execution of the RTserver, Distribution Server, and web server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Starting and stopping the Distribution Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Running services on Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Backing up and restoring Distribution Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Backing up and restoring the Distribution Server on Windows. . . . . . . . . . . . . . . 68 Backing up and restoring the Distribution Server on UNIX . . . . . . . . . . . . . . . . . . 68 Moving the Distribution Server to a different computer . . . . . . . . . . . . . . . . . . . . . . . . 69 Moving the Distribution Server to a new computer . . . . . . . . . . . . . . . . . . . . . . . . . 69 Changing the RTserver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Changing the RTserver on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Changing the RTserver on UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Updating accounts or passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Encrypting passwords. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Updating the Distribution Server account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Updating the Distribution Client default and registration accounts . . . . . . . . . . . 76 Updating the Distribution Client account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Directory structure for the Distribution Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Directory structure for the Distribution Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Environment variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Firewall configuration information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Loading a component conflict override file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Version arbitration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Component conflict overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Loading an override file for version arbitration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Where to go from here . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Chapter 4 Using the Distribution Manager 85

Introducing Distribution Manager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Where to use the Distribution Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86


6 Distribution Server Getting Started

Web browser configuration requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Logging on to the Distribution Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 The Distribution Manager interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Workflow overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Setting up products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 About components and the repository. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Importing components into the repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 About collections and components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Creating a collection and adding components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 About configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Configuring a collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Setting up systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 About accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Adding an account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 About profiles and directories on remote systems . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Creating a profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 About systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Adding systems and installing the Distribution Client . . . . . . . . . . . . . . . . . . . . . 100 Registering systems with locally installed Distribution Clients. . . . . . . . . . . . . . 101 About system groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Creating a system group and adding members . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Setting up distributions and running reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 About distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Setting up a distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 About reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Running a report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Logging off . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Where to go from here. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Chapter 5 Using the Distribution Server Command Line Interface 107 109 109 109 109 110 110 111 112 112 113 113 114 114 114 115 115 117 117 119
7

Uses of the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Where to run the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modes for running the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Command line arguments for the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running the CLI in interactive mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running the CLI with an input file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CLI commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Typographical conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Command syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Encrypting passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Exiting interactive mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Connecting to and disconnecting from a Distribution Server . . . . . . . . . . . . . . . Managing components in the repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents

Managing systems groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Managing accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 Managing profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Installing the Distribution Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 Managing Distribution Client upgrades and removals . . . . . . . . . . . . . . . . . . . . . 125 Managing distributions and distribution items. . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 Managing distribution schedules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Managing operating systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Managing reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 Managing preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 Overriding component conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 Example scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Example 1: Adding systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Example 2: Distributing products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 Example 3: Uninstalling products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 Chapter 6 Using pkgcreate 137

Packaging custom components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 pkgcreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Custom import feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 PATROL Package Format (PPF) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 Support for pkgcreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 Running pkgcreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 Where to run pkgcreate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 Running pkgcreate on UNIX systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 Running pkgcreate on Windows systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 Argument descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 Source directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 Destination directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 Minimum required arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 Specifying destination directory and operating system. . . . . . . . . . . . . . . . . . . . . 144 Importing the package into the Distribution Server . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 Chapter A Troubleshooting Distribution Server 147

Installation problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 The progress indicator remains at 99%. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 The Distribution Client is not imported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 Uninstallation problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 The InstallEngine subdirectory is not uninstalled . . . . . . . . . . . . . . . . . . . . . . . . . 148 Distribution Client problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 The Distribution Client and Distribution Server cannot communicate . . . . . . . . 149 A local installation of the Distribution Client failed . . . . . . . . . . . . . . . . . . . . . . . . 150 A deployment (or remote installation) of the Distribution Client failed . . . . . . . 152 The Distribution Client has a problem with a required account . . . . . . . . . . . . . 153 The Distribution Client failed to register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 The Distribution Client failed to run due to a system lock-down . . . . . . . . . . . . 155 Common usage problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
8 Distribution Server Getting Started

The Distribution Manager web page is not available (Error 404) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Distribution Manager web page is not available (Error 503) . . . . . . . . . . . . I cannot log on using some accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I am prompted for an additional CD when importing components . . . . . . . . . . A configuration question does not apply to my systems . . . . . . . . . . . . . . . . . . . UNIX user authentication problems with the Distribution Server . . . . . . . . . . . Distribution fails on RedHat and SUSE platforms if the CORRECT environment variable is set to cmd . . . . . . . . . . . . . . . . . . . . . . . Security related problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Gathering troubleshooting information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installation files for the Distribution Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installation logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Distribution Server logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Web server logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Distribution Client logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter B Requirements for distributing the Distribution Client from the Distribution Server

155 156 156 157 157 157 158 159 159 160 160 160 161 162

163 164 164 165 165 166 166 166 167 168 169 171 174 175 177 178 180 180 181 181 182 182 183 183 183 184 185 186 187
9

About distributing the Distribution Client from the Distribution Server . . . . . . . . . Discovering the platform of the target system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Copying and executing the installation package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Registering the Distribution Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About installation methods for distributing the Distribution Client . . . . . . . . . . . . . Setting and prioritizing installation methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using a PATROL Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reading the registry (Windows only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using a mapped drive and task scheduler service (Windows only) . . . . . . . . . . Using SFTP and SSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using FTP and Telnet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About simultaneous distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About timeouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter C Using advanced security

About web communications versus non-web communications . . . . . . . . . . . . . . . . . About security policies and security levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Security policies for the Distribution Server and related components . . . . . . . . About security level mapping for web communications . . . . . . . . . . . . . . . . . . . About the provided certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Certificate signing authorities for the provided certificates . . . . . . . . . . . . . . . . . Expiration dates for the provided certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuration tasks for advanced security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring the web server for security level 1 or 2 . . . . . . . . . . . . . . . . . . . . . . . Configuring the web server and web browser for security level 3 or 4 . . . . . . . Adding the provided trusted root certificate authority to IIS . . . . . . . . . . . . . . . Adding the provided web server certificate to IIS . . . . . . . . . . . . . . . . . . . . . . . . . Requiring client certificates on IIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing the provided certificate to a web browser . . . . . . . . . . . . . . . . . . . . . . .
Contents

About unattended and attended modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 About replacing the default certificate for the Apache web server . . . . . . . . . . . . . . 189 About unattended and attended modes for the Apache web server . . . . . . . . . . 189 Replacing the default certificate for Apache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 About distributing components with advanced security . . . . . . . . . . . . . . . . . . . . . . . 191 Chapter D Distribution failure messages 193

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 List of distribution failure messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 Distribution did not happen, system not ready . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Distribution did not happen - incomplete host data . . . . . . . . . . . . . . . . . . . . . . . 196 Distribution on system failed - multiple versions on some components . . . . . . 196 Distribution on system failed - cache size too small . . . . . . . . . . . . . . . . . . . . . . . . 196 Distribution on system did not happen - configuration locales do not match . . 197 Distribution on system did not happen - configuration error detected. . . . . . . . 197 Distribution on system did not happen - ds client not found . . . . . . . . . . . . . . . . 198 Distribution on system did not happen - not enough free disk space . . . . . . . . . 198 Wake-up call to client failed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 Timed out during distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 Timed out during installation phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 The installation completed but without components to update in inventory . . 199 Done-failed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 The distribution failed due to error on root account . . . . . . . . . . . . . . . . . . . . . . . 200 The installation did not happen due to cache check failure . . . . . . . . . . . . . . . . . 200 The installation completed but failed on post installation action. . . . . . . . . . . . . 201 The installation completed with interim errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 Distribution on system did not happen - Nothing to deploy (message is displayed on Distribution Status Report) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 Index 203

10

Distribution Server Getting Started

Chapter

1
12 12 14 15 15 15 16 16 17 17

Product components and capabilities


This chapter gives an overview of each part of the Distribution Server and discusses product documentation. This chapter is organized as follows: What is the Distribution Server? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Components of the distribution system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Distribution Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Distribution Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Distribution Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Distribution Server Command Line Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Related documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing online Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing books and release notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Where to go from here. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 1

Product components and capabilities

11

What is the Distribution Server?

What is the Distribution Server?


You use the Distribution Server to perform remote installations or uninstallations of BMC Software distributed systems products across multiple systems from a central location. With the Distribution Server you can
s

Install, reinstall, upgrade, and uninstall products on remote systems from one central location. Create collections of products and system groups to distribute multiple products to multiple systems in one distribution. Schedule a distribution for a specific date and time. Maintain multiple versions of products to be distributed. View reports to check distribution status, gather distribution data, and diagnosis problems.

Components of the distribution system


This section discusses the components that make up the distribution system.
s s s s

Distribution Server (includes web server and RTserver) Distribution Client Distribution Manager Distribution Server Command Line Interface

12

Distribution Server Getting Started

Components of the distribution system

Figure 1

Components of the Distribution System

Web browser Point a web browser to the Distribution Manager web site to administer the Distribution Server.

Distribution Server Command Line Interface Use this interface when you do not want to use a web browser.

Distribution Server RTserver This server includes a repository of components and their configurations a list of systems and an inventory of their components distribution schedules

Web server

Distribution Client Install the Distribution Client locally or through the Distribution Server.

Chapter 1

Product components and capabilities

13

Distribution Server

Distribution Server
The Distribution Server performs the following tasks.
s s s s s

houses the repository of products maintains collections, systems, and configuration information hosts the web server used to support the Distribution Manager retrieves information from the Distribution Client instructs the Distribution Client when to install or uninstall which products

The Distribution Server uses a web server and an RTserver.

Web server
The Distribution Server uses a web server to do the following:
s s s s

Distribute components Communicate with Distribution Clients Host the web site for Distribution Manager Receive log files

On UNIX, you must use the Apache web server that is installed when you install the Distribution Server. On Windows 2000, you must use an existing Microsoft Internet Information Services 5.0 (IIS). On Windows 2003, you must use an existing Microsoft Internet Information Services 6.0 (IIS).

RTserver
The Distribution Server uses an RTserver for internal communications between the Distribution Server and the
s s

Web server Distribution Server Command Line Interface

By default, an RTserver is installed when you install the Distribution Server. It is good practice to use the RTserver that is installed together with the Distribution Server. However, you can use an RTserver on a different computer. For more information about RTserver, see PATROL Console Server and RTserver Getting Started.

14

Distribution Server Getting Started

Distribution Client

Distribution Client
The Distribution Client is a small program that runs on remote systems to which you want to distribute products. The Distribution Client runs continuously, ready to respond to any of the following requests from the Distribution Server:
s s s s s

return information about the systems operating environment install or uninstall products update the client configuration file for the Distribution Server upgrade the Distribution Client itself post log files about installations

Distribution Manager
The Distribution Manager is the main user interface for the Distribution Server. You use it to access all of the functionality of the Distribution Server. The Distribution Manager runs in a web browser.

Distribution Server Command Line Interface


The Distribution Server Command Line Interface (CLI) is a text-based interface for the Distribution Server. You can access all of the functionality of the Distribution Server with it. The CLI is always installed when you install the Distribution Server. However, you can also install the CLI on a different computer.

Chapter 1

Product components and capabilities

15

Support status

Support status
BMC Software supports the following product versions and releases:
Product Name and Version Distribution Server 7.5.02 Distribution Server 7.5.01 Distribution Server 7.5.00 Distribution Server 7.1.21 Distribution Server 7.1.20 Distribution Server 7.1.15 Level of Support Full Full Full Limited Limited Limited

For more information about the latest support policies, see the Customer Support website at http://www.bmc.com/support_home.

Related documentation
The Distribution Server is supported by the following documents:
s s s s s s

Distribution Server Getting Started (this document) Distribution Manager Help Distribution Server Release Notes Installation Utility Reference Manual PATROL Console Server and RTserver Getting Started PATROL Security User Guide

Accessing online Help


The Distribution Manager Help provides detailed instructions on how to use the Distribution Manager. The following table describes a variety of methods for accessing the Help within the Distribution Manager.
For Help on . . . Distribution Manager individual pages dialog boxes Do This Click the Help button at the top right of the screen. Click the Page help button at the top right of the page. Click the Help button on the dialog box.

16

Distribution Server Getting Started

Accessing books and release notes

Accessing books and release notes


This book is provided in the Distribution Server kit. You can view this book in electronic format or order additional printed copies from the web at http://www.bmc.com/support.html. For the latest updates to product information, refer to the release notes, which are available at http://www.bmc.com/support.html.

Where to go from here


For information about... installing the Distribution Server administering and configuring your environment for distribution using the Distribution Manager See... Chapter 2, Installing the Distribution Server and the Installation Utility Reference Manual Chapter 3, Administering and configuring the Distribution Server Chapter 4, Using the Distribution Manager

using the Distribution Server Command Appendix 5, Using the Distribution Server Line Interface Command Line Interface

Chapter 1

Product components and capabilities

17

Where to go from here

18

Distribution Server Getting Started

Chapter

2
21 21 21 23 25 26 26 27 27 27 28 28 28 33 35 36 37 40 44 44 44 47 48 49 52 54 55 55

Installing the Distribution Server


This chapter provides information that you need to install the Distribution Server. For more information about how to run the installation utility and the differences between types of installations, see the Installation Utility Reference Manual. This chapter discusses the following topics: Implementation considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Base installation directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deciding how to install the Distribution Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . Network requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using more than one Distribution Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Choosing a Default or a Custom installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Alternate uses of the Distribution Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Use only the BMC Software installation utility to install the Distribution Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About the installation utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing the Distribution Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Workflow for installing the Distribution Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installable components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Required information for a Default installation of the Distribution Server . . . . . Required information for a Custom installation of the Distribution Server. . . . . Upgrading the Distribution Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Distribution Server installation worksheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing Distribution Server on Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing Distribution Server on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing the Distribution Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Workflow for installing the Distribution Client locally . . . . . . . . . . . . . . . . . . . . . . Required information for a Default, local installation of the Distribution Client Required information for a Custom, local installation of the Distribution Client Distribution Client installation worksheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing the Distribution Client locally on Windows . . . . . . . . . . . . . . . . . . . . . . Installing the Distribution Client locally on UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . About uninstalling products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Local uninstallation with product CD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Executable file for the uninstallation program . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 2

Installing the Distribution Server

19

Use the latest version of the uninstallation program . . . . . . . . . . . . . . . . . . . . . . . . 55 Using a CD to uninstall products in a Windows environment. . . . . . . . . . . . . . . . 56 Using a CD to uninstall products in a UNIX environment . . . . . . . . . . . . . . . . . . . 56 Where to go from here . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

20

Distribution Server Getting Started

Implementation considerations

Implementation considerations
This section describes several things to consider when implementing the Distribution Server.

Base installation directories


All BMC Software products, including the Distribution Server and Distribution Client, that are installed on a single system must be installed into the same base directory. The Distribution Server enforces this requirement by always installing products into the installation directory specified in the profile for a system. Even if you package your own components, they will also be installed in the base directory or one of its sub-directories. BMC Software recommends using the same base directory on all systems whenever possible to avoid confusion. It is not recommended to use the root directory as the base installation directory.

Deciding how to install the Distribution Client


You must install the Distribution Client on each system that you want to use with the Distribution Server. There are two methods of installing the Distribution Client:
s s

Distribute the Distribution Client from the Distribution Server Install the Distribution Client locally

Which method you choose depends largely on whether the network and systems meet the requirements for installing the Distribution Client from the Distribution Server. If some target systems meet the requirements, but others do not, you can use the appropriate method for each system. For more information, see Appendix B, Requirements for distributing the Distribution Client from the Distribution Server. In both methods you must create a connection account and privileged account on the target system and add the accounts to the Distribution Server.

Chapter 2

Installing the Distribution Server

21

Deciding how to install the Distribution Client

Distribute the Distribution Client from the Distribution Server


In this method you add the systems to the Distribution Server first, then distribute the Distribution Client from the Distribution Server. This method is easier if the network and systems meet the requirements for distributing the Distribution Client from the Distribution Server.

NOTE
Installing the Distribution Client from the Distribution Server is also called initializing the system, or doing a pristine install.

Install the Distribution Client locally


In this method you install the Distribution Client locally, then register the Distribution Client with the Distribution Server. The profile for the system is created automatically if an appropriate profile does not already exist. If the network or systems do not meet the requirements for installing the Distribution Client from the Distribution Server for security or other reasons, you must use this method.

22

Distribution Server Getting Started

Network requirements

Network requirements
The Distribution Server requires a properly installed TCP/IP local area network. The following diagram shows the different communication protocols used by the Distribution Server.

Web browser

Distribution Server Command Line Interface

tcp

Distribution Client

http / https http / https

RTserver

Distribution Server

tcp

Web server

Distributing the Distribution Client: 1. PATROL Agent 2. Reading the registry 3. mapped drive and Task Scheduler service 4. sftp and ssh 5. ftp and telnet Notifying Distribution Client of new distributions: ping

Chapter 2

various, see callout

Installing the Distribution Server

23

Network requirements

General network requirements


In general, both the Distribution Server and the Distribution Client must be able to resolve each other by name. The following table lists common methods used to resolve systems by name.
Method DNS Comments If the DNS allows listing all systems in the domain, you can perform system discovery to add systems. See the Distribution Manager Help for more information. Windows only. You will not be able to perform system discovery. Windows only. You will not be able to perform system discovery. You will not be able to perform system discovery.

WINS NetBIOS HOST file

Note that if you add a system using the IP address, the Distribution Server does not have to be able to resolve the Distribution Client by name. However, the Distribution Client still must be able to resolve the Distribution Server by name.

Network requirements for distributing the Distribution Client


The Distribution Server has several methods of distributing the Distribution Client: 1. PATROL Agent 2. Reading the registry (Windows only, used only to discover the platform of the target system) 3. Mapped Drive and Task Scheduler service (Windows only) 4. SFTP and SSH 5. FTP and Telnet For more information about these methods, see Appendix B, Requirements for distributing the Distribution Client from the Distribution Server. If the network or systems do not meet the requirements for any of the methods of installing the Distribution Client, you must install the Distribution Client locally.

24

Distribution Server Getting Started

Using more than one Distribution Server

Network requirements for distributing components


When a new distribution is available, the Distribution Server pings the Distribution Client. If you do not allow the Distribution Server to ping the Distribution Client, you must configure the profile for the Distribution Client to periodically check for new distributions. For more information, see the Distribution Manager Help. The Distribution Client uses http (or https for security levels higher than basic security) for the following:
s s s

Send messages to the Distribution Server Retrieve distributions from the Distribution Server Retrieve upgrades from the Distribution Server

The Distribution Client must be able to resolve the Distribution Server by name. This means that the Distribution Client can ping the Distribution Server using the Distribution Server host name, not the IP address.

Firewall requirements
If there is a firewall between any of the computers, you must create filters to allow the appropriate communications. For more information, see Firewall configuration information on page 82.

Network security
The Distribution Server, like any server in your environment, may be vulnerable to viruses or malicious attacks by remote users. Protect the Distribution Server with precautions such as investing in virus protection software and configuring the permissions of the operating system to deny access to sensitive directories and files.

Using more than one Distribution Server


Each Distribution Client can be used with only one Distribution Server. However, you can set up multiple Distribution Servers on separate computers, each with its own set of Distribution Clients. Each Distribution Server can have its own set of components and users as well as systems, so that users can distribute their own components to their own systems without having access to other systems or components.

Chapter 2

Installing the Distribution Server

25

Choosing a Default or a Custom installation

Choosing a Default or a Custom installation


The installation utility provides both Default and Custom installation types.
s

The Default installation allows you to install all components for either the Distribution Server or the Distribution Client at the same time. You will be asked only for mandatory configuration information. The defaults will be used for all optional configuration information. The Custom installation allows you to install individual components. You will be asked for both mandatory and optional configuration information.

You must use the Custom installation in the following cases:


s

You want to use a security level greater than basic security. You want to install only the Distribution Server Command Line Interface. You want to specify the port numbers the components use to communicate with each other.

Alternate uses of the Distribution Server


Even if you do not want to use the Distribution Server to distribute products, you can use it for the following:
s

The Distribution Server can be a repository for products and components. You can then export installable packages for use in a third-party or in-house distribution system. The Distribution Server can generate reports listing which BMC Software products are installed on which remote systems.

Use only the BMC Software installation utility to install the Distribution Server
You must use the installation utility provided by BMC Software to install the Distribution Server because a Distribution Server cannot deploy another Distribution Server. The installation utility, however, provides some features that might help you install the Distribution Server on remote systems.

26

Distribution Server Getting Started

About the installation utility

About the installation utility


The BMC Software installation utility runs in a web browser. You can use the installation utility to perform a local installation or uninstallation. The installation utility includes the following features. For more information, see the Installation Utility Reference Manual.
s

You can install to remote computers in your environment by creating an installable product image that can be transferred to and installed locally on those computers. You can install to a computer that does not have a web browser by launching the installation utility from a command line and specifying the -serveronly command line option. This option starts the installation web server on the computer that does not have a browser, and you can then connect to that web server using a browser on another computer.

NOTE
If you use pop-up blocker software to prevent pop-up windows from being displayed in your web browser, you must temporarily disable the software on the computer on which you want to install products to run the installation utility. The procedures and requirements for disabling pop-up blocker software vary depending on the software that you are using. Consult the documentation provided with the pop-up blocker software for instructions.

Installing the Distribution Server


This section describes how to install the Distribution Server, including the Apache web server (UNIX only) and RTserver.

Chapter 2

Installing the Distribution Server

27

Workflow for installing the Distribution Server

Workflow for installing the Distribution Server


1
Review system requirements and select a computer.

Review required information for an installation.

Complete the Distribution Server installation worksheet.

4 Create accounts
indicated in installation information.

Install the Distribution Server.

Installable components
The following table lists components that can be installed as part of Distribution Server.
Component Distribution Server Comment This is the primary component of the Distribution Server. It maintains the repository of products and collections, systems, and configuration information. It instructs the Distribution Client to install or uninstall products.

Distribution Server This component allows you to use the Distribution Server when you do not want Command Line Interface to use a web browser. It is always included with the Distribution Server. Distribution Client RTserver This component runs on remote computers to which you want to distribute products. This component is used for Distribution Server internal communications, and for communications with the Distribution Server Command Line Interface.

Required information for a Default installation of the Distribution Server


You need to know the following information before installing the Distribution Server. The Default installation option allows you to select only the Distribution Server. You cannot select or deselect individual components. You will be asked for only mandatory configuration information.

28

Distribution Server Getting Started

Required information for a Default installation of the Distribution Server

Installing from a remote drive (Windows only)


Part of the installation process involves importing the Distribution Client from the installation CD. If you install the Distribution Server from a remote drive, the Distribution Server will be unable to import the Distribution Client. You can determine if the Distribution Client was successfully imported by looking for it in the component repository when you access the Distribution Manager web site. If the Distribution Client is missing from the repository and you want to be able to install the Distribution Client from the Distribution Server, you must manually import the Distribution Client. You follow the same procedure for importing the Distribution Client as for importing any other product.

About using the IIS web server (Windows Only)


If you choose to use a Windows computer, Microsoft Internet Information Server or Microsoft Internet Information Services (IIS) must already be installed on the computer.
Windows Version Windows 2000 Windows 2003 IIS Version IIS 5.0 IIS 6.0

The installation will add an ISAPI filter named pslsp to the default IIS web site. It will also add the following virtual directories: components, hosts, and pslsp.

Default web site for IIS


If the default web site is turned off, you must turn it on. You cannot use a different web site.

Required IIS accounts


The following IIS accounts are required on the Distribution Server system:
s s

Internet Guest Launch IIS Process

The Distribution Server uses IIS for all server-client activity such as client registration, product distribution, and product inventory reports. If you remove these accounts, server-client functions fail even when using the Distribution Server Command Line Interface.

Chapter 2

Installing the Distribution Server

29

Required information for a Default installation of the Distribution Server

ISAPI extensions for IIS on Windows 2003


You cannot install and run the Distribution Server on Windows 2003 unless IIS is configured in the following way: All Unknown ISAPI Extensions must be set to Allowed. Other extensions may remain Prohibited without affecting the Distribution Server.
Start => Administrative Tools => Internet Information Services Manager => Web Service Extensions => All Unknown ISAPI Extensions

About using the Apache web server (UNIX only)


If you choose to use a UNIX computer, the Apache web server is installed with the Distribution Server. A new instance of Apache will be installed in the $BMC_ROOT/common directory, even if there already is an instance of Apache elsewhere on the computer. If there will be multiple web servers on the computer, you must make certain that they do not use conflicting ports. For more information, see Web server HTTP and HTTPS port numbers on page 34.

TIP
For more information about Apache, see the Apache HTTP Server web site at http://httpd.apache.org or the Apache documentation installed with Apache at http://hostname:port/manual, where hostname is the name of the server, and port is its HTTP port. The Apache license information is installed with Apache at $BMC_ROOT/common/apache/apache.1.3.33/platform/htdocs/manual/LICENSE.

Base installation directory


The base installation directory is the location where you install all BMC Software products. Additional directories will be created under the base installation directory. On Microsoft Windows, the default for this directory is C:\Program Files\BMC Software. On UNIX, the default for this directory is /opt/bmc. This directory cannot be changed after the installation. For more information, see Base installation directories on page 21.

30

Distribution Server Getting Started

Required information for a Default installation of the Distribution Server

Distribution Server account


Before you install the Distribution Server, you must create an operating system account for the Distribution Server to use. Although you may select an existing user account, BMC Software recommends that you create a separate user account for the Distribution Server. PATROL users can use the PATROL account as the Distribution Server account. You must be logged on as this account when you run the installation. When you install the Distribution Server, you must also specify the password of this account.
Platform UNIX Windows Distribution Server Requirements This account must have read, write, and execute permissions for the base installation directory. This account must belong to the local Administrators group on the Distribution Server system. This account must have the following user rights, which are assigned automatically by the installation utility:
s s s

act as part of operating system log on as a service replace a process level token

This account can be a domain user account or a local account. However, if you want domain users to be able to access the Distribution Server, this account must be a domain account.

Root account (UNIX only)


When you install the Distribution Server on UNIX, you must specify the password for the root account. If you do not know the password for the root account, you can run the installation, then have someone with root authority run the ds_config.sh script in the $BMC_ROOT/Patrol7/bin/platform directory to complete the installation. Alternatively, you can create a sudo-privileged account and enter the sudo account and password in place of the root account and password. For details on installing and setting up sudo, see Installing and configuring sudo to create a privileged account to deploy products on page 97.

Chapter 2

Installing the Distribution Server

31

Required information for a Default installation of the Distribution Server

Distribution Client default account


The Distribution Client default account is a server-side account used whenever a Distribution Client needs to send or receive information about a product distribution task, such as when the Distribution Client tries to get the installation task information from the server, or when the Distribution Client wants to post the resulting installation log files back to the server. This account must exist on the Distribution Server computer before you install the Distribution Server. You can use the same account for both the Distribution Server account and the Distribution Client default account. Merging these accounts simplifies the installation of the Distribution Server; however, you might want to consider the security implications because the Distribution Server account requires high privileges and the client default account requires only low privileges.

TIP
This account is unrelated to the Distribution Client account and privileged account used by the Distribution Client.

Apache user name and group (UNIX only)


Before you install the Distribution Server, you must create an operating system account and group for the Apache web server to use. The installation will ask you for the user name and group. The user and group are used to run the HTTPD child daemons and to protect the files. The root account is usually used to start HTTPD. The account should belong to only the web server group for security purposes. Do not use this account for any other purposes.

File system permissions for Apache


The Apache account must be able to search all parent directories of the directory where Apache is installed. Ensure that all parent directories of the base installation directory have the x-bit set in the permissions for at least the Apache account. For more information, see the Apache FAQ.

Example commands for creating the account and group


To create a user and group, both called wwwadmin, and give the account a password, issue the following commands as root:
groupadd wwwadmin useradd -m -g wwwadmin wwwadmin passwd wwwadmin 32 Distribution Server Getting Started

Required information for a Custom installation of the Distribution Server

RTserver variable setting


The installation asks for the RTserver variable setting. This variable is used by the web server and Distribution Server Command Line Interface to connect to the RTserver. The format of the RTSERVERS environment variable is tcp:computer_name:port_number, in which computer_name is the name of a computer on which the RTserver is installed, and port_number is the port at which the RTserver is listening. The default for this environment variable is tcp:localhost:2059. You should use the default value for this variable, unless you want to use an RTserver on a different computer from the Distribution Server, or you change the port number in a custom installation. For more information, see the PATROL Console Server and RTserver Getting Started Guide.

WARNING
If you use an RTserver on a different computer from the Distribution Server, install the RTserver first and ensure that it is running before you install the Distribution Server.

Required information for a Custom installation of the Distribution Server


If you select a custom installation, you need to know all of the information for a default installation (Required information for a Default installation of the Distribution Server on page 28), plus you can change the default settings for the following.

Distribution Client registration account


The registration account is a server-side account used anytime a potential Distribution Client attempts to register to the Distribution Server as ready for product distribution. This is typically done when the Distribution Client is installed locally, when the Distribution Client is restarted, or when the system is restarted. This account can be the same as the Distribution Client default account. For example, in a default installation, they are the same. This account should be a low privileged account. It must have the same rights as the Distribution Client default account. For more information, see Distribution Client default account on page 32.

Chapter 2

Installing the Distribution Server

33

Required information for a Custom installation of the Distribution Server

This account must exist on the Distribution Server computer before you install the Distribution Server.

TIP
These accounts are unrelated to the Distribution Client account and privileged account used by the Distribution Client.

Web server HTTP and HTTPS port numbers


The web server uses http and https for communications with both web browsers accessing the Distribution Manager web site and with Distribution Clients. Whether the web server uses secure or insecure communications depends on the security level. For basic security and security level 1, the web server uses http. For security levels 2, 3, or 4, the web server uses https. For more information, see Security on page 35. The default http port is 80. The default https port is 443. If you do not use the default ports the user will have to include the appropriate port number in the URL for accessing the Distribution Manager web site. For example, if the web server myserver is using port 8080 for http, view the URL http://myserver:8080/pslsp/DsManager.

Considerations for the HTTP and HTTPS ports when using the apache web server
The installation of Apache will use the http and https ports that you specify. If there will be multiple web servers on the system, ensure that each web server uses a different set of ports.

Considerations for the HTTP and HTTPS ports when using the IIS web server
You must enter the http and https ports used by IIS on the default web site. You cannot change the ports by entering different numbers.

RTserver port setting


The RTserver uses this port to listen for communications. The default is 2059. This port number and the port number in the RTserver variable setting must match. See RTserver variable setting on page 33.

34

Distribution Server Getting Started

Upgrading the Distribution Server

Trimming Apache web server log files (Apache only)


The Apache web server log file can grow considerably over the course of time. For example, each image load request is logged. The installation installs a utility that truncates the log files for the Apache web server while the web server is running, so that they do not grow without limit. This utility can be run periodically as a job in the root crontab. You can choose the maximum log file size. The same maximum size is applied to each log file. The default value is 20 MB.

Security
You must set the level of security that you want to use. The default is basic security. The security level must be compatible with the security level of the components that the Distribution Server will be communicating with, such as the Distribution Client. If you want to use advanced security, see Appendix C, Using advanced security and the PATROL Security User Guide for more information.

Upgrading the Distribution Server


To upgrade the Distribution Server, install the new version over the top of the one that is currently installed. While performing an over the top installation (OTI), consider a couple of issues: starting and stopping services on MS-Windows and compatibility with Distribution Clients.

Starting and stopping services on Windows


On Windows, OTI requires that you manually stop the following services in the specified order: 1. 2. 3. 4. 5. FTP Publishing Service Network News Transport Protocol (NNTP) Simple Mail Transport Protocol (SMTP) World Wide Web Publishing Service IIS Administration Service

The installation utility restarts the World Wide Web Publishing Service and IIS Administration Service, but you must restart all of the other services manually after the installation is complete.

Chapter 2

Installing the Distribution Server

35

Distribution Server installation worksheet

Compatibility with Distribution Clients


Upgrade a Distribution Server before upgrading the Distribution Clients because the upgraded server can communicate with clients that have not been upgraded. Upgraded clients cannot communicate with servers that have not been upgraded. Upgrading a client first breaks the communication with the server until you can upgrade the server.

Distribution Server installation worksheet


Use this worksheet to record information about your Distribution Server installation.
Computer Name: What components do you want to run on this computer?
s s s

Distribution Server Distribution Server Command Line Interface RTserver

Are you installing from a remote drive? yes / no If yes, you must manually import the Distribution Client. Web server Where do you want to install BMC Software products? The default is /opt/bmc on UNIX, and C:\Program Files\BMC Software on Windows. Are you upgrading on MS-Windows? If yes, did you stop these services? For more information, see Upgrading the Distribution Server on page 35.
s s s s s s s

Apache (UNIX) IIS (Windows)

FTP Publishing Service Network News Transport Protocol (NNTP) Simple Mail Transport Protocol (SMTP) World Wide Web Publishing Service IIS Administration Service

Accounts What is the Distribution Server account name? You must create this account before the installation. What is the Distribution Client default account name? You must create this account before the installation. What is the Distribution Client registration account name? You must create this account before the installation.a You will need the root login name and password. (UNIX only) Web Server Information What is the Web server http port? The default is 80.b What is the Web server https port? The default is 443.b What is the Apache HTTPD user account name? You must create this account before the installation. (UNIX only)

36

Distribution Server Getting Started

Installing Distribution Server on Windows

What is the Apache HTTPD group name? You must create this group before the installation. (UNIX only) Maximum size for log files. The default is 20 MB. (UNIX only)b Automatically add job to trim log files to crontab? (UNIX only) The default is yes.b For IIS on Windows 2003, is All Unknown ISAPI Extensions set to Allowed? For more information, see About using the IIS web server (Windows Only) on page 29. RTserver Information What is the RTserver variable? The default is tcp:localhost:2059.b What is the RTserver port? The default is 2059.b If you use an RTserver on a different computer from the Distribution Server, what is the name of the RTserver computer? Warning: If on a different computer, the RTserver must be running before you install the Distribution Server. Security Information What security level do you want to use? The default is basic.b
s s s s s

yes / no

yes / no

basic level 1 level 2 level 3 level 4

If you want the Distribution Client registration account to be different from the Distribution Client default account, you must use a custom installation. If you do not use the default, you must use a custom installation.

Installing Distribution Server on Windows


This task describes how to install Distribution Server from the installation CD onto a Windows computer. For more information about how to run the installation utility, see the Installation Utility Reference Manual. This task applies to both a default and a custom installation. However, the illustrations reflect a default installation. If you choose a custom installation, the web pages you see will be slightly different.

Chapter 2

Installing the Distribution Server

37

Installing Distribution Server on Windows

Before you begin


The computer must meet the system requirements. For more information, see Required information for a Default installation of the Distribution Server on page 28. You must know the required information for the type of installation you will perform. For more information, see Choosing a Default or a Custom installation on page 26, Required information for a Default installation of the Distribution Server on page 28, and Required information for a Custom installation of the Distribution Server on page 33. The accounts described in Required information for a Default installation of the Distribution Server on page 28 must exist on the computer. You must be logged on as the Distribution Server account. You must disable any pop-up blocker software to run the installation utility.

To install Distribution Server on Windows 1 Insert the Distribution Server CD into the CD drive and run setup.exe at the root of
the CD.

2 On the Welcome to the Installation Utility page, click Next to continue. 3 On the Review License Agreement page, read the license agreement. If you accept
it, select Accept. Then click Next.

4 On the Select Installation Option page, select Install products on this computer now.
Then click Next. For more information about creating an installable image, see the Installation Utility Reference Manual.

5 On the Specify Installation Directory page, type or browse to the location where
you want to install BMC Software products. Then click Next. For more information about the installation directory, see Base installation directory on page 30.

6 On the Select Type of Installation page, select Default or Custom as the installation
type. Then click Next. For more information about the different types of installation, see Choosing a Default or a Custom installation on page 26, Required information for a Default installation of the Distribution Server on page 28, and Required information for a Custom installation of the Distribution Server on page 33.
38 Distribution Server Getting Started

Installing Distribution Server on Windows

7 On the Select Products and Components to Install page, expand Distribution


Services, then select Distribution Server. Then click Next.

8 Complete the Distribution Server Properties page. A Type the Distribution Server account password and confirm it. For more
information, see Distribution Server account on page 31.

B If you selected a custom installation, type the web server HTTP and HTTPS port
numbers. For more information, see Web server HTTP and HTTPS port numbers on page 34.

C If you selected a custom installation, select whether to stop and restart IIS
during the installation.

D Click Next. 9 On the Distribution Server mapped accounts page, type the Distribution Client
default account name and password, and confirm the password. If you selected a custom installation, also type the Distribution Client registration account name and password and confirm the password. Then click Next. For more information, see Distribution Client default account on page 32 and Distribution Client registration account on page 33.

10 If you selected a custom installation, on the Select Level of Security page, select
advanced or basic security and whether to overwrite the current security configuration. Then click Next. For more information, see Security on page 35, Appendix C, Using advanced security and the PATROL Security User Guide.

11 If you selected a custom installation and selected Advanced security, complete the
security information. There might be multiple pages, depending on your choices. Click Next as you complete each page. For more information, see Security on page 35, Appendix C, Using advanced security and the PATROL Security User Guide.

12 On the Provide Startup Information for RTserver page, select Yes to install
RTserver. Also accept the default port number for RTserver to use, or type a new one. Then click Next. For more information about the RTserver port setting, see RTserver port setting on page 34.

13 On the RTservers Variable Properties page, accept the default value for the
RTserver variable setting, or type a new value. Then click Next.

Chapter 2

Installing the Distribution Server

39

Installing Distribution Server on UNIX

For more information, see RTserver variable setting on page 33.

14 On the Distribution Server post processing page, review and record the URL for
the Distribution Manager graphical user interface, including the use of http versus https. You will use this URL to access the Distribution Manager. Then click Next. If you selected a custom installation, also review the information about security levels. For more information, see Appendix C, Using advanced security.

15 On the Review Selections and Install page, review your selections. Then click Start
Install.

16 Watch the Installation Status page to verify that the installation process completes
successfully. When the installation is 100% complete, click Next.

NOTE
During the installation process, the Percentage Complete progress indicator may appear to be stopped at 99%. The system is completing post-installation scripts and will move to the Installation Results page when finished.

17 On the Installation Results page, click View Log to review the installation log file.
When you are done, click Next to continue then click Finish. The components are now installed on your system.

Installing Distribution Server on UNIX


This task describes how to install Distribution Server from the installation CD onto a UNIX computer. For more information about how to run the installation utility, see the Installation Utility Reference Manual. This task applies to both a default and a custom installation. However, the illustrations reflect a default installation. If you choose a custom installation, the web pages you see will be slightly different.

Before you begin


The computer must meet the system requirements. For more information see Required information for a Default installation of the Distribution Server on page 28.

40

Distribution Server Getting Started

Installing Distribution Server on UNIX

You must know the required information for the type of installation you will perform. For more information, see Choosing a Default or a Custom installation on page 26, Required information for a Default installation of the Distribution Server on page 28, and Required information for a Custom installation of the Distribution Server on page 33. The accounts described in Required information for a Default installation of the Distribution Server on page 28 must exist on the computer. You must be logged on as the Distribution Server account. You must disable any pop-up blocker software to run the installation utility.

To install Distribution Server on UNIX 1 Insert the Distribution Server CD into the CD drive, mount the CD, and
run ./setup.sh at the root of the CD.

2 On the Welcome to the Installation Utility page, click Next to continue. 3 On the Review License Agreement page, read the license agreement. If you accept
it, select Accept. Then click Next.

4 On the Select Installation Option page, select Install products on this computer now.
Then click Next. For more information about creating an installable image, see the Installation Utility Reference Manual.

5 On the Specify Installation Directory page, type or browse to the location where
you want to install BMC Software products. Then click Next. For more information about the installation directory, see Base installation directory on page 30.

6 On the Select Type of Installation page, select Default or Custom as the installation
type. Then click Next. For more information about the different types of installation, see Choosing a Default or a Custom installation on page 26, Required information for a Default installation of the Distribution Server on page 28, and Required information for a Custom installation of the Distribution Server on page 33.

7 On the Select Products and Components to Install page, expand Distribution


Services, then select Distribution Server. Then click Next.

Chapter 2

Installing the Distribution Server

41

Installing Distribution Server on UNIX

8 On the Provide the System Root Account Properties page, type the password for
the root account. Then click Next. For more information, see Root account (UNIX only) on page 31.

9 Complete the Distribution Server Properties page. Then click Next. A Type the Distribution Server account password. For more information, see
Distribution Server account on page 31.

B If you selected a custom installation, type the web server HTTP and HTTPS port
numbers. For more information, see Web server HTTP and HTTPS port numbers on page 34.

10 On the Distribution Server mapped accounts page, type the Distribution Client
default account name and password, and confirm the password. If you selected a custom installation, also type the Distribution Client registration account name and password and confirm the password. Then click Next. For more information, see Distribution Client default account on page 32 and Distribution Client registration account on page 33.

11 If you selected a custom installation, on the Select Level of Security page, select
advanced or basic security and whether to overwrite the current security configuration. Then click Next. For more information, see Security on page 35, Appendix C, Using advanced security and the PATROL Security User Guide.

12 If you selected a custom installation and selected Advanced security, complete the
security information. There might be multiple pages, depending on your choices. Click Next as you complete each page. For more information, see Security on page 35, Appendix C, Using advanced security and the PATROL Security User Guide.

13 If you selected a custom installation, on the Apache HTTP Server Parameters page,
type the Apache HTTPD user account name and HTTPD group. Then click Next. For more information, see Apache user name and group (UNIX only) on page 32.

14 If you selected a custom installation, complete the Configure Apache for


Distribution Server page. Then click Next.

42

Distribution Server Getting Started

Installing Distribution Server on UNIX

A Select whether to check and limit the size of the Apache log files automatically
or manually.

B Specify the maximum size in megabytes for the Apache log files.
For more information, see Trimming Apache web server log files (Apache only) on page 35.

15 On the Provide Startup Information for RTserver page, accept the default port
number for the RTserver to use, or type a new one. Then click Next. For more information about the RTserver port setting, see RTserver port setting on page 34.

16 On the RTserver Variable Properties page, accept the default value for the
RTserver variable setting, or type a new value. Then click Next. For more information, see RTserver variable setting on page 33.

17 On the Distribution Server post processing page, review and record the URL for
the Distribution Manager graphical user interface, including the use of http versus https. You will need to use this URL to access Distribution Manager. Then click Next. If you selected a custom installation, also review the information about security levels. For more information, see Appendix C, Using advanced security.

18 On the Review Selections and Install page, review your selections. Then click Start
Install.

19 Watch the Installation Status page to verify that the installation process completes
successfully. When the installation is 100% complete, click Next.

NOTE
During the installation process, the Percentage Complete progress indicator may appear to be stopped at 99%. The system is completing post-installation scripts and will move to the Installation Results page when finished.

20 On the Installation Results page, click View Log to review the installation log file.
When you are done, click Next to continue then click Finish. The components are now installed on your system.

Chapter 2

Installing the Distribution Server

43

Installing the Distribution Client

Installing the Distribution Client


There are two methods of installing the Distribution Client:
s s

Install the Distribution Client from the Distribution Server. Install the Distribution Client locally.

For more information about choosing a method, see Deciding how to install the Distribution Client on page 21. For more instructions on installing the Distribution Client from the Distribution Server, see Setting up systems on page 94.

Workflow for installing the Distribution Client locally


1
Review system requirements.

Review required information for an installation.

Complete Distribution Client installation worksheet.

4 Create accounts
indicated in installation information.

Install the Distribution Client.

In Distribution Manager, register the system.

Required information for a Default, local installation of the Distribution Client


You need to know the following information before installing the Distribution Client locally.

Base installation directory


The base installation directory is the location where you install all BMC Software products. Additional directories will be created under the base installation directory.

44

Distribution Server Getting Started

Required information for a Default, local installation of the Distribution Client

On Microsoft Windows, the default for this directory is C:\Program Files\BMC Software. On UNIX, the default for this directory is /opt/bmc. When you create a profile for this system in Distribution Manager, the base installation directory in the profile must match this directory. If you were to install the Distribution Client using the Distribution Server, you would indicate this directory in the profile for the system. This directory cannot be changed after the installation. For more information, see Base installation directories on page 21.

WARNING
The base installation directory must be different from the working directory.

Distribution Server web server host name


The Distribution Server host name is the name of the Distribution Server that you want to use with this Distribution Client. The Distribution Client must be able to resolve this name to an IP address. If you were to install the Distribution Client using the Distribution Server, the Distribution Server would send this information to the Distribution Client.

Distribution Client working directory and maximum size


The Distribution Client uses this directory to store distributed files from the Distribution Server. You cannot change the location of the working directory later without uninstalling and reinstalling the Distribution Client. You can change the maximum size of the working directory later by changing the profile for this system in Distribution Manager. When you create a profile for this system in Distribution Manager, the working directory in the profile must match this directory. However, you can indicate a different size. If you were to install the Distribution Client using the Distribution Server, you would indicate this information in the profile for the system.

Chapter 2

Installing the Distribution Server

45

Required information for a Default, local installation of the Distribution Client

WARNING
The working directory must be different from the base installation directory.

Distribution Client account


Before you install the Distribution Client, you must have an operating system account on the Distribution Client computer for the Distribution Client to use. This account is used to run the Distribution Client and install distributions. The Distribution Client has the following general requirements:
s

You must be logged on as this account when you run the installation. When you install the Distribution Client, you must also specify the user name and password of this account. The account must be the same account used by other BMC Software products installed in the same directory.

Distribution Client account requirements on Windows


On Microsoft Windows platforms, BMC Software highly recommends that you use one account for all of the following accounts:
s s s

Distribution Client account connection account privileged account

On the Distribution Client system, the account must be a member of the users group and Administrators group (but not the Administrator account itself), have write access to the file system, and have the right to connect remotely. The account can be a local or domain account. If you use a local account, enter only the account name. If you use a domain account, preface the account name with the domain. The account also must have the following user rights:
s s s s

act as part of operating system increase quotas log on as a service replace a process level token

46

Distribution Server Getting Started

Required information for a Custom, local installation of the Distribution Client

A local installation of the Distribution Client automatically assigns these rights to the account. Installing it from the Distribution Server, however, does not assign these rights. For a remote installation, assign these rights manually using the operating system.

Distribution Client account requirements on UNIX


On UNIX platforms, you must use the same account for the Distribution Client account and the connection account. You cannot use the same account for the privileged account because this account must be root or a sudo-privileged account. The Distribution Client account must be the same account used by other BMC Software products installed in the same directory, and it must have write access to the file system.

Root account (UNIX only)


When you install the Distribution Client on UNIX, you must specify the password for the root account. If you do not know the password for the root account, you can run the installation, then have someone with root authority run the ds_config.sh script in the $BMC_ROOT/dsclient/bin/platform directory to complete the installation. Alternatively, you can create a sudo-privileged account and enter the sudo account and password in place of the root account and password. For details on installing and setting up sudo, see Installing and configuring sudo to create a privileged account to deploy products on page 97.

Required information for a Custom, local installation of the Distribution Client


If you select a Custom installation, you need to know all of the information for a Default installation, plus the information in this section.

Distribution Server web server HTTP and HTTPS port numbers


The Distribution Client needs to know which ports to use to communicate with the Distribution Server. These ports must match the HTTP and HTTPS ports used when the Distribution Server was installed.

Chapter 2

Installing the Distribution Server

47

Distribution Client installation worksheet

If you were to install the Distribution Client using the Distribution Server, the Distribution Server would send this information to the Distribution Client.

Distribution Client port number


The Distribution Server uses this port to contact the Distribution Client. You can change this port number later by changing the profile for this system in Distribution Manager. When you create a profile for this system in Distribution Manager, you can specify the same port number or a different one. If you were to install the Distribution Client using the Distribution Server, you would indicate this port number in the profile for the system.

Restart option (UNIX only)


You can choose whether you want to restart the Distribution Client after a system reboot. If you choose to restart the Distribution Client (the default), the script for starting the Distribution Client is added to the rc files. If you choose to not restart the Distribution Client, you must manually start the Distribution Client after a system reboot.

Security
You must set the level of security that you want to use. The default is basic security. The security level must be compatible with the security level of the Distribution Server. If you want to use advanced security, see Appendix C, Using advanced security and the PATROL Security User Guide for more information.

Distribution Client installation worksheet


Use this worksheet to record information about your Distribution Client installation.
Computer Name: Where do you want to install BMC Software products? The default is /opt/bmc on UNIX, and C:\Program Files\BMC Software on Windows.

48

Distribution Server Getting Started

Installing the Distribution Client locally on Windows

What is the Distribution web server host name? What is the Distribution Client port? The default is 50005. a What is the working directory? The default is c:\temp\dsc on Windows. What is the working directory maximum size? The default is 300 MB.a What is the Distribution Client account? You must create this account before the installation. You will need the root login name and password. (UNIX only) Restart the Distribution Client on system reboot? (UNIX only) The default is yes.a Security Information What security level do you want to use? The default is basic.a
a
s s s

**** yes / no

basic level 2 level 4

If you do not use the default, you must use a custom installation.

Installing the Distribution Client locally on Windows


This task describes how to install Distribution Client locally on a Windows computer. For more information about how to run the installation utility, see the Installation Utility Reference Manual. This task applies to both a default and a custom installation. However, the illustrations reflect a default installation. If you choose a custom installation, the web pages you see will be slightly different.

Before you begin


The computer must meet the system requirements. For more information see Required information for a Default, local installation of the Distribution Client on page 44. You must know the required information for the type of installation you will perform. For more information, see Choosing a Default or a Custom installation on page 26, Required information for a Default, local installation of the Distribution Client on page 44, and Required information for a Custom, local installation of the Distribution Client on page 47. The account described in Required information for a Default, local installation of the Distribution Client on page 44 must exist on the computer. You must be logged on as the Distribution Client account.

Chapter 2

Installing the Distribution Server

49

Installing the Distribution Client locally on Windows

You must disable any pop-up blocker software to run the installation utility.

To install Distribution Client locally on Windows 1 Insert the Distribution Server CD into the CD drive and run setup.exe at the root of
the CD.

2 On the Welcome to the Installation Utility page, click Next to continue. 3 On the Review License Agreement page, read the license agreement. If you accept
it, select Accept. Then click Next.

4 On the Select Installation Option page, select Install products on this computer now.
Then click Next. For more information about creating an installable image, see the Installation Utility Reference Manual.

5 On the Specify Installation Directory page, type or browse to the location where
you want to install BMC Software products. Then click Next. For more information about the installation directory, see Base installation directory on page 30.

6 On the Select Type of Installation page, select Default or Custom as the installation
type. Then click Next. For more information about the different types of installation, see Choosing a Default or a Custom installation on page 26.

7 On the Select Products and Components to Install page, expand Distribution


Services, then select Distribution Server Client. Then click Next.

8 Complete the Distribution Server Client properties page. Then, click Next. A Type the Distribution web server host name.
For more information, see Distribution Server web server host name on page 45.

B If you chose a custom installation, type the web server HTTP and HTTPS port
numbers. For more information, see Distribution Server web server HTTP and HTTPS port numbers on page 47.

C If you chose a custom installation, type the port number for the Distribution
Client.
50 Distribution Server Getting Started

Installing the Distribution Client locally on Windows

For more information, see Distribution Client port number on page 48.

D Type the location of the Distribution Client working directory and its maximum
size. For more information, see Distribution Client working directory and maximum size on page 45.

E Type the Distribution Client password and confirm it.


For more information, see Distribution Client account on page 46.

F Click Next. 9 If you chose a custom installation, on the Select Level of Security page, select
advanced or basic security and whether to overwrite the current security configuration. Then click Next. For more information, see Security on page 35, Appendix C, Using advanced security and the PATROL Security User Guide.

10 If you selected a custom installation and selected Advanced security, complete the
security information. There might be multiple pages, depending on your choices. Click Next as you complete each page. For more information, see Security on page 35, Appendix C, Using advanced security and the PATROL Security User Guide.

11 If you selected a custom installation, review the information about the Distribution
Server Client post processing page. Then click Next.

12 On the Review Selections and Install page, review your selections. Then click Start
Install.

13 Watch the Installation Status page to verify that the installation process completes
successfully. When the installation is 100% complete, click Next.

14 On the Installation Results page, click View Log to review the installation log file.
When you are done, click Next to continue then click Finish. The components are now installed on your system.

Chapter 2

Installing the Distribution Server

51

Installing the Distribution Client locally on UNIX

Installing the Distribution Client locally on UNIX


This task describes how to install Distribution Client locally on a UNIX computer. This task applies to both a default and a custom installation. However, the illustrations reflect a default installation. If you choose a custom installation, the web pages you see will be slightly different. For more information about how to run the installation utility, see the Installation Utility Reference Manual.

Before you begin


The computer must meet the system requirements. For more information see Required information for a Default, local installation of the Distribution Client on page 44. You must know the required information for the type of installation you will perform. For more information, see Choosing a Default or a Custom installation on page 26, Required information for a Default, local installation of the Distribution Client on page 44, and Required information for a Custom, local installation of the Distribution Client on page 47. The accounts described in Required information for a Default, local installation of the Distribution Client on page 44 must exist on the computer. You must be logged on as the Distribution Client account. You must disable any pop-up blocker software to run the installation utility.

To install Distribution Client locally on UNIX 1 Insert the Distribution Server CD into the CD drive, mount the CD, and
run ./setup.sh at the root of the CD.

2 On the Welcome to the Installation Utility page, click Next to continue. 3 On the Review License Agreement page, read the license agreement. If you accept
it, select Accept. Then click Next.

4 On the Select Installation Option page, select Install products on this computer now.
Then click Next. For more information about creating an installable image, see the Installation Utility Reference Manual.

5 On the Specify Installation Directory page, type or browse to the location where
you want to install BMC Software products. Then click Next.

52

Distribution Server Getting Started

Installing the Distribution Client locally on UNIX

For more information about the installation directory, see Base installation directory on page 30.

6 On the Select Type of Installation page, select Default or Custom as the installation
type. Then click Next. For more information about the different types of installation, see Choosing a Default or a Custom installation on page 26.

7 On the Select Products and Components to Install page, expand Distribution


Services, then select Distribution Server Client. Then click Next.

8 On the Provide the System Root Account Properties page, enter the name of the
root account, root password, and confirm root password. Root account (UNIX only) on page 47

9 Complete the Distribution Server Client properties page. Then, click Next. A Type the Distribution web Server host name. For more information, see
Distribution Server web server host name on page 45.

B If you selected a custom installation, type the web server HTTP and HTTPS port
numbers. For more information, see Distribution Server web server HTTP and HTTPS port numbers on page 47.

C If you chose a custom installation, type the port number for the Distribution
Client. For more information, see Distribution Client port number on page 48.

D Type the location of the Distribution Client working directory and its maximum
size. For more information, see Distribution Client working directory and maximum size on page 45.

E Type the Distribution Client account name. For more information, see
Distribution Client account on page 46.

F If you chose a custom installation, select whether to automatically restart the


Distribution Client after a system reboot. For more information, see Restart option (UNIX only) on page 48.

G Click Next. 10 If you selected a custom installation, on the Select Level of Security page, select
advanced or basic security and whether to overwrite the current security configuration. Then click Next. For more information, see Security on page 35, Appendix C, Using advanced security and the PATROL Security User Guide.

Chapter 2

Installing the Distribution Server

53

About uninstalling products

11 If you selected a custom installation and selected Advanced security, complete the
security information. There might be multiple pages, depending on your choices. Click Next as you complete each page. For more information, see Security on page 35, Appendix C, Using advanced security and the PATROL Security User Guide.

12 If you selected a custom installation, review the information about the Distribution
Server Client post processing page. Then click Next.

13 On the Review Selections and Install page, review your selections. Then click Start
Install.

14 Watch the Installation Status page to verify that the installation process completes
successfully. When the installation is 100% complete, click Next.

15 On the Installation Results page, click View Log to review the installation log file.
When you are done, click Next to continue then click Finish. The components are now installed on your system.

About uninstalling products


There are different procedures for uninstalling products, depending on how the product was installed.
s

To uninstall the Distribution Server, use the local uninstallation. For more information, see the Installation Utility Reference Manual. To uninstall products on remote systems using the Distribution Server, schedule a distribution in uninstall mode. The products must exist in the repository of the Distribution Server. For more information, see the Distribution Manager Help. To uninstall the Distribution Client using the Distribution Server, have the Distribution Server remove the Distribution Client from the remote system. For more information, see the Distribution Manager Help. To perform a local uninstallation on a remote system when all of the BMC Software products on it have been distributed from the Distribution Server, you need a CD with the installation utility to perform the local uninstallation. For more information, see Local uninstallation with product CDin the following section.

54

Distribution Server Getting Started

Local uninstallation with product CD

Local uninstallation with product CD


This section explains how to locally uninstall products that were deployed by the Distribution Server.

Executable file for the uninstallation program


A local installation creates the following file:
s s

$BMC_ROOT/Uninstall/uninstall.sh (UNIX) %BMC_ROOT%\Uninstall\uninstall.exe (Windows)

The installation utility creates this file so you can launch the uninstallation utility from your local hard drive. When you distribute products, the Distribution Server does not create this file because most users of the Distribution Server want the convenience of uninstalling products remotely. If you must uninstall BMC Software products locally, verify whether the uninstallation file exists on the local drive. If it does not, all of the products on the system were installed by the Distribution Server, and you need a product CD from BMC Software to perform the local uninstallation. This section describes how to perform this type of local uninstallation.

Use the latest version of the uninstallation program


Typically, you should use the uninstallation program that is on the product CD for the Distribution Server because this CD should contain the latest version of the uninstallation program. Each time that you install a BMC Software product, that version of the installation utility modifies common resources for all BMC Software products on that system. These modifications might not be compatible to earlier versions of the installation utility. For example, assume that the Distribution Client uses the 7.5.21 version of the installation utility. If you deploy the Distribution Client from the Distribution Server, all BMC Software products on the client system can be removed only by the 7.5.21 version of the uninstallation program. During the client deployment, version 7.5.21 modified common areas used by all BMC Software products. Even if a BMC Software program on that system typically uses the 7.4.60 version of the installation utility, it now requires the 7.5.21 version of the uninstallation utility because that was the highest version used on that system.

Chapter 2

Installing the Distribution Server

55

Using a CD to uninstall products in a Windows environment

NOTE
You can download the latest version of the installation utility at the following site: ftp://ftp.bmc.com/pub/patrol/patches.

Using a CD to uninstall products in a Windows environment


This task shows how to locally uninstall BMC Software products when the uninstallation program does not exist on the local hard drive. These instructions are specific to the Windows platform.

To use a CD to uninstall products 1 Execute the CD_drive:\uninstall.exe file, where CD_drive is the drive letter for the
CD drive that holds the product CD. The Welcome page is displayed. Click Next.

2 Select the installation directory from which you want to remove a product. Click
Next.

3 Select the product or products that you want to uninstall. Click Next. 4 Review your selections and click Uninstall.
Once the uninstallation is complete, a page is displayed that tells you the status of the uninstallation.

Using a CD to uninstall products in a UNIX environment


This task shows how to locally uninstall BMC Software products when the uninstallation program does not exist on the local hard drive. These instructions are specific to UNIX platforms.

To use a CD to uninstall products 1 Change the directory to the CD drive that holds the product CD and enter the
following command to launch the installation utility in uninstall mode:
./uninstall.sh

The Welcome page is displayed. Click Next.


56 Distribution Server Getting Started

Where to go from here

2 Select the installation directory from which you want to remove a product. Click
Next.

3 Select the product or products that you want to uninstall. Click Next. 4 Review your selections and click Uninstall.
Once the uninstallation is complete, a page is displayed that tells you the status of the uninstallation.

Where to go from here


For information about... See... administering and configuring your Chapter 3, Administering and configuring the environment for the Distribution Server Distribution Server using the Distribution Manager Chapter 4, Using the Distribution Manager using the Distribution Server Command Appendix 5, Using the Distribution Server Line Interface Command Line Interface

Chapter 2

Installing the Distribution Server

57

Where to go from here

58

Distribution Server Getting Started

Chapter

Administering and configuring the Distribution Server


3

This chapter contains information for administering and configuring the Distribution Server. This chapter discusses the following topics: Setting up accounts and groups for users on the Distribution Server . . . . . . . . . . . . . 61 Starting and stopping programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Starting and stopping the RTserver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Starting and stopping the Distribution Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Starting and stopping the web server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Verifying the installation and execution of the RTserver, Distribution Server, and web server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Starting and stopping the Distribution Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Running services on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Backing up and restoring Distribution Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Moving the Distribution Server to a different computer. . . . . . . . . . . . . . . . . . . . . 69 Backing up and restoring the Distribution Server on UNIX . . . . . . . . . . . . . . . . . . 68 Moving the Distribution Server to a different computer . . . . . . . . . . . . . . . . . . . . . . . . 69 Moving the Distribution Server to a new computer . . . . . . . . . . . . . . . . . . . . . . . . 69 Changing the RTserver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Changing the RTserver on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Changing the RTserver on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Updating accounts or passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Encrypting passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Updating the Distribution Server account. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Updating the Distribution Client default and registration accounts . . . . . . . . . . . 76 Updating the Distribution Client account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Directory structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Directory structure for the Distribution Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Directory structure for the Distribution Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Firewall configuration information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Chapter 3

Administering and configuring the Distribution Server

59

Loading a component conflict override file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Version arbitration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Component conflict overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Loading an override file for version arbitration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Where to go from here . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

60

Distribution Server Getting Started

Setting up accounts and groups for users on the Distribution Server

Setting up accounts and groups for users on the Distribution Server


The Distribution Server uses operating system user accounts and groups to control privileges for users when they log on. Users inherit the privileges of the groups that they belong to. User accounts can be local or domain accounts. However, groups must be local groups. The following table lists the groups with predefined privileges. If these groups do not already exist, they are created when you install the Distribution Server. You can also create and assign privileges to additional local groups.
Group patadm patpop patop patscadm Description users can perform all functions users can perform most functions, except set administrative options users can run reports

Add the account for each user of the Distribution Server to the appropriate operating system group. When a user connects to the Distribution Server from the Distribution Manager or the Distribution Server Command Line Interface, the user logs on with an operating system account. The Distribution Server uses the operating system account to identify the user, the groups that the user belongs to, and the privileges that the user has. On Windows, if you want to be able to import components from a remote server, the account must be a domain account. For more information about changing privileges, see the Distribution Manager Help.

Starting and stopping programs


This section contains the basic steps for starting the following programs, verifying that they are running, and stopping them. All of the following programs must be running in order to use the Distribution Server, even if you are not actively using Distribution Manager. Start them in the following order: 1. RTserver 2. Distribution Server 3. Web Server (Apache or IIS)

Chapter 3

Administering and configuring the Distribution Server

61

Starting and stopping the RTserver

This section also incudes the basic steps for starting the Distribution Client, verifying that it is running, and stopping it.

NOTE
By default, the Distribution Server and Distribution Client are started automatically and you do not need to start them manually.

Starting and stopping the RTserver


By default, the RTserver is started automatically when you install it. However, you can start it manually. This task describes how to start the RTserver on both Windows and UNIX and verify that it is running.

NOTE
For more information about starting RTserver, see the PATROL Console Server and RTserver Getting Started Guide.

To start, stop, or verify the execution of RTserver on Windows


Start, stop, or verify the execution of the SmartSockets RTserver service. For more information, see Running services on Windows on page 67.

To manually start the RTserver on UNIX 1 Change to the $BMC_ROOT/common/smartsockets directory. 2 Enter the following command:
./start_rtserver.sh

To verify that RTserver is running on UNIX 1 Enter the following command:


ps -ef | grep rtserver

2 Look for the rtserver process.

62

Distribution Server Getting Started

Starting and stopping the Distribution Server

To stop RTserver on UNIX 1 Change to the $BMC_ROOT/common/smartsockets directory. 2 Enter the following command:
./stop_rtserver.sh

Starting and stopping the Distribution Server


The Distribution Server is run as a service on Windows and as a daemon on UNIX. By default, the Distribution Server is started automatically when you install it. However, you can start it manually. This task describes how to start the Distribution Server on both Windows and UNIX and verify that it is running.

Before you begin


Verify that the RTserver is running. For more information, see Starting and stopping the RTserver on page 62.

To start, stop, or verify the execution of the Distribution Server on Windows


Start, stop, or verify the execution of the BMC Distribution Server service. For more information, see Running services on Windows on page 67.

To manually start the Distribution Server on UNIX 1 Change to the $BMC_ROOT/Patrol7/bin/platform directory. 2 Enter the following command:
./ds_start.sh

To verify that the Distribution Server is running on UNIX 1 Enter the following command:
ps -ef | grep ds

2 Look for the ds process.

Chapter 3

Administering and configuring the Distribution Server

63

Starting and stopping the web server

To stop the Distribution Server on UNIX 1 Change to the $BMC_ROOT/Patrol7/bin/platform directory. 2 Enter the following command, where username and password are the user name and
password of the Distribution Server account.
./ds_stop.sh username password

NOTE
You can enter the password in plain text or use encryption. For more information, see Encrypting passwords on page 74.

Starting and stopping the web server


By default, the Apache web server is started automatically when you install it, and the IIS web server is stopped and restarted when you install the Distribution Server. This task describes how to start the web server and verify that it is running.

Before you begin


Ensure that the Distribution Server is running. For more information, see Starting and stopping the Distribution Server on page 63.

To start, stop, or verify the execution of the IIS web server on Windows
Refer to your IIS documentation.

To manually start the Apache web server on UNIX 1 Set the user to root. 2 Change to the $BMC_ROOT/common/bmc/ directory. 3 Enter the following command to set the environment variables:
./patrol7rc.sh

4 Change to the $BMC_ROOT/common/apache/apache.version/platform/bin/ directory.

64

Distribution Server Getting Started

Verifying the installation and execution of the RTserver, Distribution Server, and web server

5 Enter one of the following commands, depending on the security level used when
the web server was installed:
s s

./apachectl.bmc -DDSNOSSL start (basic security level) ./apachectl.bmc startssl (security levels 1 through 4)

To verify that the Apache web server is running on UNIX 1 Enter the following command:
ps -ef | grep apache

2 Look for the apache process. To stop the Apache web server on UNIX 1 Set the user to root. 2 Change to the $BMC_ROOT/common/apache/apache.version/platform/bin/ directory. 3 Enter the following command:
./apachectl.bmc stop

Verifying the installation and execution of the RTserver, Distribution Server, and web server
You can verify that the RTserver, Distribution Server, and web server are running by viewing the URLs in the table below. In the URL to view, hostname is the name of the web site. Typically, this is the name of the computer on which the Distribution Server is running. If the web server is not using the default port for http, include the port number in the URL. For example, if the web server myserver is using port 8080, view the URL http://myserver:8080/pslsp/DsManager.

NOTE
The RTserver, Distribution Server, and web server must be started in order.

Chapter 3

Administering and configuring the Distribution Server

65

Starting and stopping the Distribution Client

What to Verify

URL to View

Comments If the default page for the web server is displayed, the web server is running. If the default page for the web server is displayed, https is active. If you are prompted to log on, the Distribution Server and RTserver are running. If you use advanced security, use https instead of http.

Is the web server running? http://hostname Is https active for the web server? Are the RTserver and Distribution Server, and web server running and started in the correct order? https://hostname http:/hostname/pslsp/DsManager

Starting and stopping the Distribution Client


The Distribution Client is run as a service on Windows and as a daemon on UNIX. By default, the Distribution Client is started automatically when you install it (either locally, or using the Distribution Server). However, you can start it manually. This task describes how to start the Distribution Client on both Windows and UNIX and verify that it is running.

To start, stop, or verify the execution of the Distribution Client on Windows


Start, stop, or verify the execution of the BMC Distribution Client service. For more information, see Running services on Windows on page 67.

To manually start the Distribution Client on UNIX 1 Change to the $BMC_ROOT/dsclient/bin/platform directory. 2 Enter the following command:
./listener_ctl.sh start

To verify that the Distribution Client is running on UNIX 1 Enter the following command:
ps -ef | grep ds_listener

2 Look for the ds_listener process.

66

Distribution Server Getting Started

Running services on Windows

To stop the Distribution Client on UNIX 1 Change to the $BMC_ROOT/dsclient/bin/platform directory. 2 Enter the following command:
./listener_ctl.sh stop

Running services on Windows


On Windows, you use the Services dialog box to start, stop, and verify the execution of services.

To start a service 1 Open the Control Panel and select Administrative Tools. 2 Double-click the Services icon. 3 Select the name of the service. 4 Choose Action => Properties, then click Start. To verify that a service is running 1 Open the Services dialog box. 2 Look at the status of the service. To stop a service 1 Open the Services dialog box. 2 Select the name of the service. 3 Choose Action => Properties, then click Stop.

Chapter 3

Administering and configuring the Distribution Server

67

Backing up and restoring Distribution Server

Backing up and restoring Distribution Server


BMC Software recommends that you back up the Distribution Server on a regular basis.

Backing up and restoring the Distribution Server on Windows


This task describes how to back up and restore the Distribution Server on Windows.

To back up the Distribution Server on Windows 1 Stop the Distribution Server. 2 Back up the %BMC_ROOT% directory. To restore the Distribution Server on Windows 1 Reinstall the Distribution Server. 2 Restore the backed up files.

Backing up and restoring the Distribution Server on UNIX


This task describes how to back up and restore the Distribution Server on UNIX.

To back up the Distribution Server on UNIX 1 Stop the Distribution Server. 2 Back up the following directories:
s s s

$BMC_ROOT /opt/bmc /etc/patrol.d

68

Distribution Server Getting Started

Moving the Distribution Server to a different computer

To restore the Distribution Server on UNIX 1 Restore the backed up files. 2 If you do not have root authority, have someone with this authority run the
ds_config.sh script located in the $BMC_ROOT/Patrol7/bin/platform directory.

Moving the Distribution Server to a different computer


You can move the Distribution Server from one computer to a different computer. For example, if you have set up the Distribution Server on a test computer, you can move it to a production computer. Moving the Distribution Server from one computer to a different computer involves the following:
s

Installing the Distribution Server on the new computer and moving the data to the new computer Having existing Distribution Clients use the new Distribution Server

Moving the Distribution Server to a new computer


This task describes how to move the Distribution Server files to a new computer.

NOTE
This task overwrites and replaces any Distribution Server data files on the new

computer.

To move the Distribution Server files to a new computer 1 Ensure that there are no active or pending distributions. 2 Stop the Distribution Server on the original computer. 3 Back up all of the files in the $BMC_ROOT/ds directory. 4 Install the Distribution Server on the new computer.

Chapter 3

Administering and configuring the Distribution Server

69

Moving the Distribution Server to a new computer

5 Stop the Distribution Server on the new computer, and restore the backed up
directory.

6 Start the RTserver, Distribution Server, and web server on the new computer. 7 If you have Distribution Clients set up, switch them to the new Distribution Server.
See the following process.

To switch a Distribution Client to a new Distribution Server: local configuration


This procedure describes how to configure the local system that hosts the client. To remotely perform this same task, see To switch a Distribution Client to a new Distribution Server: remote configuration on page 71.

1 Stop the Distribution Client, as described in Starting and stopping the


Distribution Client on page 66.

2 Open the following directory on the system that hosts the Distribution Client:
s s

$BMC_ROOT/dsclient/config (UNIX)

%BMC_ROOT%\dsclient\config (Windows)

3 Use a text editor to modify the BMC_DS_TSERVER_URL value in the dsclient.ini to


the URL of the new Distribution Server.

4 Remove the dshostid.conf file. 5 Restart the Distribution Client. 6 Use a web browser to log on to the new Distribution Server, as described in
Logging on to the Distribution Manager on page 87.

7 Using the Distribution Manager, run the System Registration report and register
the Distribution Client.

70

Distribution Server Getting Started

Changing the RTserver

To switch a Distribution Client to a new Distribution Server: remote configuration


You can perform all steps in this procedure from the Distribution Manager. For an alternative procedure, see To switch a Distribution Client to a new Distribution Server: local configuration on page 70.

1 Use a web browser to log on to the Distribution Server to which the Distribution
Client is currently connected, as described in Logging on to the Distribution Manager on page 87.

2 Use the Remove Clients command on the Options tab to remove the Distribution
Client.

3 Disconnect from the current Distribution Server, and log on to the new
Distribution Server.

4 Add the computer to the new Distribution Server and install the Distribution
Client, as described in Adding systems and installing the Distribution Client on page 100.

Changing the RTserver


You specify several settings during the installation of the Distribution Server. You can change some of those settings after installation. You specify the RTserver during the installation of the Distribution Server. If you want to switch to a different RTserver, or if you typed the RTserver incorrectly in the installation, you can change the RTserver after installation. If you install the Distribution Server Command Line Interface on a different computer from the Distribution Server, you can also change the RTserver that it uses.

Changing the RTserver on Windows


This task describes how to change the RTserver used by the Distribution Server on Windows.

To change the RTserver for the Distribution Server on Windows 1 Edit the RTSERVERS system environment variable to reflect the new RTserver. 2 Stop and restart the Distribution Server.
Chapter 3 Administering and configuring the Distribution Server 71

Changing the RTserver on UNIX

3 Use a text editor to open the pslsp_isapi.reg file in the %PATROL_ROOT%\config\


directory. Determine whether the value of PslSp_RTLocator is correct for the new RTserver, and change it if necessary.

EXAMPLE
"PslSp_RTLocator" = "tcp:localhost:2059"

4 Load the changes into the Windows registry:


s s

On 32-bit Windows computers, double-click pslsp_isapi.reg. On 64-bit Windows computers, run the following command:

%SystemRoot%\SysWOW64\regedt32.exe /S BMC_ROOT\Patrol7\config\pslsp_isapi.reg

NOTE
BMC_ROOT is the base installation directory.

5 Stop and restart the web server. To change the RTserver for the Distribution Server Command Line Interface on Windows
Edit the RTSERVERS system environment variable to reflect the new RTserver.

Changing the RTserver on UNIX


This task describes how to change the RTserver used by the Distribution Server on UNIX.

To change the RTserver for the Distribution Server on UNIX 1 If the RTSERVERS environment variable has been set for the current shell, clear the
value.

2 Modify the patrol7rc.sh or patrol7rc.csh script to reflect the new RTserver.


These scripts are located in the $BMC_ROOT/common/bmc/ directory.

3 Stop and restart the Distribution Server.

72

Distribution Server Getting Started

Changing the RTserver on UNIX

4 Stop and restart the web server. To change the RTserver for the Distribution Server Command Line Interface on UNIX 1 If the RTSERVERS environment variable has been set for the current shell, clear the
value.

2 Modify the patrol7rc.sh or patrol7rc.csh script to reflect the new RTserver. 3 Execute the script. 4 Start the Distribution Server Command Line Interface.

Chapter 3

Administering and configuring the Distribution Server

73

Updating accounts or passwords

Updating accounts or passwords


You specify several accounts and passwords during the installation of the Distribution Server. You can change some of those settings after installation. If you change the password for any of the following accounts in the operating system, you must make the corresponding changes for the Distribution Server or Distribution Client. You can also change the account itself.
s

Distribution Server account. For more information about this account, see Distribution Server account on page 31. Distribution Client default account and Distribution Client registration account. For more information about these accounts, see Distribution Client default account on page 32 and Distribution Client registration account on page 33. Distribution Client account. For more information about this account, see Distribution Client account on page 46.

Encrypting passwords
This task describes how to encrypt a password.

To Encrypt a Password 1 Change to the $BMC_ROOT/common/bmc/bin/platform/ directory. 2 Enter the appropriate command for your platform:
sec_encrypt_p3x plain_text_password (Windows) ./sec_encrypt_p3x plain_text_password (UNIX)

The encrypted password is returned.

74

Distribution Server Getting Started

Updating the Distribution Server account

Updating the Distribution Server account


This task describes how to change the account or password for the Distribution Server account.

To update the account or password for the Distribution Server account 1 If you are changing the account, as well as the password perform the following
steps:

A Create the account in the operating system. B Assign the account the properties specified in Distribution Server account on
page 31, including any user rights and file permissions.

C Ensure that the new account is a member of a group with the appropriate
Distribution Server privileges. For more information, see Setting up accounts and groups for users on the Distribution Server on page 61. During the original installation, the original account is added to all the pat* groups.

2 If you are changing only the password for the account, change the password in the
operating system.

3 On Windows, change the service account to reflect the updated account and
password by following these steps:

A Open the Control Panel. B Choose Administrative Tools => Services. C Double-click BMC Distribution Server. D Access the Logon tab and enter the new account or password. E Click OK. 4 On Windows, repeat step 3 to change the account/password of the RTserver if it
was installed as part of the Distribution Server.

5 Generate the encrypted password using the sec_encrypt_p3x utility.


For more information, see Encrypting passwords on page 74.

Chapter 3

Administering and configuring the Distribution Server

75

Updating the Distribution Client default and registration accounts

6 Open the patrol.conf file in a text editor.


s s

On UNIX, this file is in the /etc/patrol.d/ directory. On Windows, this file is in the %BMC_ROOT%\common\patrol.d\ directory.

7 In the [DS] stanza, modify the defaultAccount variable to reflect the new account
and encrypted password.

8 (Optional) Change the file permissions of the new account. NOTE


This step needs to be performed only if the new Distribution Server account is in a different OS group than the previous Distribution Server account.

On Windows, give the new account read and write permission for all files and subdirectories in %BMC_ROOT%\ds\repository and %BMC_ROOT%\ds\components. On UNIX, assign ownership (chown command) to the new account for all files and subdirectories in $BMC_ROOT/ds/repository and $BMC_ROOT/ds/components.

9 Restart the Distribution Server.

Example of the [DS] stanza in patrol.conf


The following is an example of the [DS] stanza of the patrol.conf file.

[DS] defaultAccount = patroli:BA4FB463EEE8E929

Updating the Distribution Client default and registration accounts


This task describes how to update the account or password for the Distribution Client default account or Distribution Client registration account on the Distribution Server.

76

Distribution Server Getting Started

Updating the Distribution Client default and registration accounts

NOTE
If you use the same account as the Distribution Client default account and the Distribution Client registration account (for example, you used a default installation), be sure to change both accounts together.

To update the account or password for the Distribution Client default or registration account 1 If you are changing the account, as well as the password perform the following
steps:

A Create the account in the operating system. B Assign the account the required properties, including any user rights and file
permissions. For more information, see Distribution Client default account on page 32 or Distribution Client registration account on page 33.

C Ensure that the new account is a member of a group with the appropriate
Distribution Server privileges. For more information, see Setting up accounts and groups for users on the Distribution Server on page 61. During the original installation, the original accounts are added to the patop and patpop groups on Windows and all the pat* groups on UNIX.

2 If you are changing only the password for the account, change the password in the
operating system.

3 Generate the encrypted password using the sec_encrypt_p3x utility.


For more information, see Encrypting passwords on page 74.

4 Open the appropriate file in a text editor:


s s

On Windows, open the %BMC_ROOT%\Patrol7\config\ds\ds_pslsp.reg file. On UNIX, open the $BMC_ROOT/Patrol7/config/ds/ds_pslsp.conf file.

5 Edit the PslSp_UserPass value, PslSp_UserName value, or both for the appropriate
account (Distribution Client default account or Distribution Client registration account).

6 Save and close the file. 7 On Windows, double-click the file to import the settings into the registry.

Chapter 3

Administering and configuring the Distribution Server

77

Updating the Distribution Client account

8 Stop and restart the web server. 9 Stop and restart the Distribution Server.

Example of the ds_pslsp.reg file


The following is an example of the ds_pslsp.reg file.

REGEDIT4 [HKEY_LOCAL_MACHINE\SOFTWARE\BMC Software\Patrol\pslsp\ds/reg.pslsp] "PslSp_UserName"="dsc_default" "PslSp_UserPass"="4CC83924449DBFAB8EF030822D38A871" [HKEY_LOCAL_MACHINE\SOFTWARE\BMC Software\Patrol\pslsp\ds/cos_execute.pslsp] "PslSp_UserName"="dsc_default" "PslSp_UserPass"="4CC83924449DBFAB8EF030822D38A871"

Updating the Distribution Client account


This task describes how to update the account or password for the Distribution Client account.

To update the account or password for the Distribution Client account on Windows 1 If you are changing the account and password, perform the following steps;
otherwise, skip to step 2:

A Create the account in the operating system. B Assign the account the properties specified in Distribution Client account on
page 46, including any user rights and file permissions.

2 If you are changing only the password for the account, change the password in the
operating system.

3 On Windows, change the service account to reflect the updated account and
password.

A Open the Control Panel. B Choose Administrative Tools => Services.

78

Distribution Server Getting Started

Directory structure

C Double-click BMC Distribution Server. D Access the Logon tab and enter the new account or password. E Click OK. 4 Stop and restart the Distribution Client. To update the account for the Distribution Client account on UNIX NOTE
The password for the Distribution Client is not used on UNIX.

1 If, during the installation of the Distribution Client, you selected to restart the
Distribution Client on reboot, perform the following:

A Locate the S99dsclient file in the /etc/rc* script section depending on the run level. B Edit the appropriate S99dsclient file and modify the tag
DSCLIENTUSER=user_name by replacing the current user name with the new

user name.

C Save the file. 2 If you do not reboot, switch to the new user name. 3 Change to the $BMC_ROOT/dsclient/bin/platform/ directory. 4 Stop and restart the Distribution Client.
For more information, see Starting and stopping the Distribution Client on page 66.

Directory structure
The directory structure for the Distribution Server is different from the directory structure for the Distribution Client

Chapter 3

Administering and configuring the Distribution Server

79

Directory structure for the Distribution Server

Directory structure for the Distribution Server


The following table describes the directories used by the Distribution Server.
Directory $BMC_ROOT $BMC_ROOT/common $BMC_ROOT/Install $BMC_ROOT/Uninstall $BMC_ROOT/itools $BMC_ROOT/Patrol7 $BMC_ROOT/Patrol7/bin $BMC_ROOT/Patrol7/log/ds $BMC_ROOT/ds $BMC_ROOT/ds/PI $BMC_ROOT/ds/repository $BMC_ROOT/ds/systems Description Where BMC Software products are installed. Contains common components that are shared by multiple products, such as security files. Contains information about which components and products are installed. Contains files for uninstalling components and products. Contains files and utilities used by the installation utility. Contains files that are used by Patrol 7 and by the Distribution Server. Contains the platform specific subdirectory where the Distribution Server is installed. Contains the Distribution Server log files. Contains the Distribution Server subdirectories. Contains the data files and utilities required for new installations of the Distribution Client. Contains the Distribution Server database. Contains the Distribution Server client mail boxes.

$BMC_ROOT/ds/components Contains the imported products directories.

NOTE
These directories refer to the sub-directories of $BMC_ROOT. By default, this is C:\Program Files\BMC Software on Windows and /opt/bmc on UNIX.

80

Distribution Server Getting Started

Directory structure for the Distribution Client

Directory structure for the Distribution Client


The following table describes the directories used by the Distribution Client.
Directory $BMC_ROOT $BMC_ROOT/common $BMC_ROOT/Install $BMC_ROOT/Uninstall Description Where BMC Software products are installed. Contains common components that are shared by multiple products, such as security files. Contains information about which components and products are installed. Contains files for uninstalling components and products. This directory will not be present if the Distribution Client was installed using the Distribution Server. Contains files and utilities used by the installation utility. Where the Distribution Client is installed. Contains platform dependent binary files. Contains language resource files used for international support. Contains configuration files for the Distribution Client. Contains the Distribution Client log files. Contains temporary security files and templates. Contains files from the Distribution Server. This directory is specified during the installation of the Distribution Client and in the profile for the system.

$BMC_ROOT/itools $BMC_ROOT/dsclient $BMC_ROOT/dsclient/bin $BMC_ROOT/dsclient/locale $BMC_ROOT/dsclient/config $BMC_ROOT/dsclient/log $BMC_ROOT/dsclient/security Working directory

NOTE
These directories refer to the sub-directories of $BMC_ROOT. By default, this is C:\Program Files\BMC Software on Windows and /opt/bmc on UNIX.

Environment variables
This section lists the environment variables used by Distribution Server. The values of these variables are assigned at installation.
Environment Variable BMC_ROOT PATROL_ROOT RTSERVERS How Variable Is Used points to the location where BMC Software products are installed equivalent to $BMC_ROOT/Patrol7 and points to the location where Distribution Server is installed identifies the RTserver that Distribution Server Command Line Interface uses

Chapter 3

Administering and configuring the Distribution Server

81

Firewall configuration information

The following environment variable is used by the Distribution Client.


Environment Variable BMC_ROOT How Variable Is Used points to the location where BMC Software products are installed

Firewall configuration information


This section describes the protocols, ports, and connection directions for setting up a firewall for the Distribution Server. The Distribution Server requires that certain ports be open in the firewall for the following features to work:
s s s s

Using the Distribution Manager web interface Using the Distribution Server Command Line interface Distributing the Distribution Client from the Distribution Server Executing Distributions

The following table lists the protocols, ports, and connection directions required for each major feature. Note that day-to-day operations involving only the Distribution Manager and executing distributions requires only one connection protocol and portHTTP:80 or HTTPS:443, depending on the security level.
Feature Protocol Default Port 80 / 443 2059 3181 135 - 139 135 - 139 21 23 115 22 80 / 443 80 / 443 50005 Distribution Client --> Distribution Server Distribution Server --> Distribution Client Connection Direction web browser --> web Server CLI --> Distribution Server Distribution Server --> target system

Distribution Manager (web HTTP /HTTPS (TCP) interface) Distribution Server Command Line Interface Distributing the Distribution Client from the Distribution Server COS (TCP, RT) PATROL (pexec) WIN MAP (SMB) WIN Remote Reg FTP Telnet SFTP SSH Distribution (pull files) Distribution (post logs) Distribution (wakeup) HTTP / HTTPS HTTP / HTTPS TCP

82

Distribution Server Getting Started

Loading a component conflict override file

Loading a component conflict override file


Some components cannot coexist in the same collection because they contain different versions of a shared sub-component. For example, component A and component B both require sub-component C, but A uses C version 1.5.00 and B uses C version 1.7.00. If you add A to a collection that already contains B, a version conflict develops because the Distribution Server can only add one version of C to the collection: 1.5.00 or 1.7.00.

Version arbitration
The Distribution Server uses version arbitration to solve component conflicts. In the previous example, the Distribution Server would use information about sub-component C to determine whether versions 1.5.00 and 1.7.00 are compatible. If yes, it chooses the appropriate version and adds component A to the collection. If the Distribution Server finds that it does not have enough information about sub-component C, it prevents you from adding component A to the collection.

Component conflict overrides


An override file provides more information about sub-components, which the Distribution Server uses to improve its ability to perform version arbitration. If you experience a component conflict, you can contact customer support at BMC Software to see whether they have an override file that solves your particular problem. If they provide an override file, load it into the Distribution Server and retry the operation, which caused the version arbitration failure.

Loading an override file for version arbitration


This task describes how to load an override file into the Distribution Server, which improves the performance of version arbitration.

To load the override file as you start the Distribution Server 1 Stop the Distribution Server if it is running. 2 Copy the override file to the following directory:
s s

$BMC_ROOT/Patrol7/lib/mof (UNIX) %BMC_ROOT%\Patrol7\lib\mof (Windows)


Chapter 3 Administering and configuring the Distribution Server 83

Where to go from here

3 Change the name of the override file to ds_component_overrides.mof (if it does not
already have this name).

4 Start the Distribution Server. To load the override file as you import a component 1 Copy the override file to the index directory of the installation image from which
you want to import a component.

2 Change the name of the override file to ds_component_overrides.mof (if it does not
already have this name).

3 Import the desired component from the installation image. To load the override file with the Distribution Server CLI
Use the coverride update command from the Distribution Server CLI. For more information about coverride update, see Overriding component conflicts on page 132.

Where to go from here


For information about... using Distribution Manager See... Distribution Manager Help using the Distribution Server Command Chapter 5, Using the Distribution Server Line Interface Command Line Interface.

84

Distribution Server Getting Started

Chapter

Using the Distribution Manager


This chapter contains information for getting started with the Distribution Manager. This chapter discusses the following topics: Introducing Distribution Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Where to use the Distribution Manager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Web browser configuration requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Logging on to the Distribution Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 The Distribution Manager interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Workflow overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Setting up products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 About components and the repository. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Importing components into the repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 About collections and components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Creating a collection and adding components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 About configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Configuring a collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Setting up systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 About accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Adding an account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 About profiles and directories on remote systems . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Creating a profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 About systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Adding systems and installing the Distribution Client . . . . . . . . . . . . . . . . . . . . . 100 Registering systems with locally installed Distribution Clients. . . . . . . . . . . . . . 101 About system groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Creating a system group and adding members . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Setting up distributions and running reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 About distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Setting up a distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 About reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Running a report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Logging off . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Where to go from here. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Chapter 4

Using the Distribution Manager

85

Introducing Distribution Manager

Introducing Distribution Manager


This section includes the following topics.
s s s s

Where to use the Distribution Manager Web browser requirements Logging on to the Distribution Manager The Distribution Manager interface

Where to use the Distribution Manager


You can use the Distribution Manager on any computer with a supported web browser and access to the Distribution Manager web site. However, if you are importing or exporting components, you might want to use a computer near the Distribution Server or on the same network. The Distribution Server cannot import from or export to a file system that is not locally accessible. The source of the import or the destination of the export must be a local drive, a mapped drive (Windows), or an NFS mounted drive (UNIX).

Web browser configuration requirements


The browser must be configured as follows:
s

The browser must check for newer versions of stored pages for every visit to the pages. JavaScript support must be turned on. The browser must enable style sheets. Pop-up blocking must be disabled.

For more information about how to configure your browser, see the documentation for your browser. Error messages and other screens in the Distribution Server Manager will not display if pop-up blocking is enabled. Disable the pop-up blocking software on the computer on which you want to run the Distribution Server Manager. The procedures and requirements for disabling pop-up blocker software vary depending on the software that you are using. Consult the documentation provided with the pop-up blocker software for instructions.
86 Distribution Server Getting Started

Logging on to the Distribution Manager

Logging on to the Distribution Manager


This task describes how to log on to the Distribution Manager.

Before you begin


You must know the following:
s s

The name of the computer where the Distribution Server is installed. The user name and password of an account on the Distribution Server with the necessary Distribution Server privileges.

To log on to the Distribution Manager 1 Point the web browser to http://hostname/pslsp/DsManager, where hostname is the
name of the system where the Distribution Server is installed. If the web server is not using the default port for http, include the port number in the URL. For example, if the web server myserver is using port 8080, view the URL http://myserver:8080/pslsp/DsManager. If you use advanced security, use https to access Distribution Manager, instead of http.

TIP
If the Distribution Server is installed on a Windows computer, and you are accessing Distribution Manager from the same computer, you can start Distribution Manager by clicking the Start button on the taskbar, then choosing Programs => BMC Distribution Server => Distribution Manager.

2 Enter your user name and password. 3 Click OK.

The Distribution Manager interface


The Distribution Manager interface is composed of the following major elements:
s

Tab Area The tab area is located at the top of the Distribution Manager interface. The tabs provide access to all of the functionality in Distribution Manager. Each tab represents a major area of functionality.

Chapter 4

Using the Distribution Manager

87

The Distribution Manager interface

List Area The list area is located at the left side of the Distribution Manager interface. This area provides a list of objects associated with a task that you are performing.

Results Area The results area is located at the right side of the Distribution Manager interface. The results area displays information as you browse the tabs or select objects from the list area.

Toolbar The toolbar is located at the upper right side of the Distribution Manager interface. The toolbar area displays the ID for the user logged on for a particular session. The toolbar also provides links for you to access Help for the current page.

88

Distribution Server Getting Started

Workflow overview

Workflow overview
Setting Up Products (A) Setting Up Systems (B)

Import components into the repository.

1 Create accounts
in the OS of the systems.

Arrange components in collections.

2 Add accounts and


create profiles for the systems.

Configure the collection.

Add the system and install the Distribution Client.

4 Arrange systems

in system groups.

Distributing Products (C)

Distribute configurations of collections to system groups.

Run reports to review distributions.

Chapter 4

Using the Distribution Manager

89

Setting up products

Setting up products
When you receive a new version of a product that you want to distribute, you import its components into the repository. When you are ready to distribute components from the repository, you create a collection defining which components you want to distribute together and how to configure them.

Import components into the repository.

Arrange components in collections.

Configure the collection.

About components and the repository


A component is any BMC Software product or component of a product that you can install from a product CD or a downloaded CD image. The components must be available to the Distribution Server on a locally accessible drive. For example, the components can be on a product CD in a CD drive accessible to the Distribution Server or downloaded from the BMC Software Electronic Product Download (EPD) site and expanded into a directory to which to the Distribution Server has access. For a complete list of what components can be imported, see the Distribution Manager Help. You import the components into the repository. The repository can maintain multiple versions of each component. You can think of the repository as a giant CD image. The Components page shows a tree view of the components and versions that have been imported. From this page, you can manage the components in the repository.

Importing components into the repository


This task describes how to import components into the repository.

Before you begin


The components must be available to the Distribution Server on a locally accessible drive.

90

Distribution Server Getting Started

About collections and components

NOTE
You cannot reactivate an inactive component by re-importing it into the repository. See the Distribution Manager Help for more information about inactive components.

To import components 1 In the tab area, click the Components tab. 2 In the list area, click the Import button. 3 Type or browse to the location where the components are located. Then click Next.
Select the directory that contains the products directory (not the products directory itself). For a CD, this is the root of the CD

4 Select the check boxes for the components that you want to import. Then click OK. 5 Click Import to import the selected components. WARNING
While an import is in progress, do not create, modify, or refresh any collections. During import, the Distribution Server might need to import dependency files that affect other components in the repository.

About collections and components


A collection is a set of components in the repository that you want to distribute together. All of the components in a collection are distributed when you distribute that collection. Which components are in a collection also impact the configurations for that collection. Although the repository might contain multiple versions of a component, a collection can include only one version of a component at a time. You can refresh a collection to ensure that it updates any hidden components in a collection that may have previously been missing from the repository, but which are available at that point of time. The Refresh collection feature refreshes the same version of a package or product but does not upgrade to a new version of that package or product. A component must belong to one or more collections in order to be distributed. To distribute a single component by itself, create a collection that includes only that component.

Chapter 4

Using the Distribution Manager

91

Creating a collection and adding components

All the components in a collection are distributed together, as if they were on a single CD image. If components were designed to be distributed serially, such as some products and their patches, do not put them in the same collection. Instead, put them in separate collections, to distribute in the appropriate order. In general, components that were not released together or that were not shipped in the same kit should be distributed serially, unless otherwise noted in the product documentation. For strategies on setting up the components in a collection, see the Distribution Manager Help.

Creating a collection and adding components


This task describes how to create a collection and add components to it.

Before you begin


The components that you want to include in the collection are in the repository.

To create a collection 1 In the tab area, click the Collections tab. 2 In the list area, click the Add button. 3 Type the name of the collection. Then click Add. 4 (optional) In the Description box, type a description of the collection. 5 Proceed with adding components to the collection. To add components to a collection 1 In the results area for the collection, click the Components sub-tab. 2 In the results area, click Add. 3 Select the check boxes for the components that you want to add. 4 Click Add. 5 Proceed with configuring the collection.

92

Distribution Server Getting Started

About configurations

About configurations
Each collection has one or more configurations, which contain installation and uninstallation information for all the components in the collection. The configuration information varies for each collection, depending on the components in the collection. If multiple components in a collection share a configuration question, that question is asked only once in the configuration, and all components use the same answer. When you create a collection, a default configuration, which uses the default responses to all configuration questions, is also created. However, for some components, the default configuration might not have enough information to successfully install or uninstall the components. For example, some components might require specific account information. You can edit or remove the default configuration and create more configurations. For strategies for setting up configurations, see the Distribution Manager Help.

Configuring a collection
This task describes how to create a configuration for a collection.

Before you begin


The collection exists and has components in it.

To create a configuration for a collection 1 In the results area for the collection, click the Configurations sub-tab for the
collection.

2 Click Add. 3 Type the name and description for the configuration. Then click Next. 4 For each screen, provide the requested information for the configuration. Then
click Next. On the last screen, click Finish. For more information about what is requested, refer to the product-specific documentation.

Chapter 4

Using the Distribution Manager

93

Setting up systems

Setting up systems
When you have a computer that you want to include in the Distribution Server, you perform the following tasks. Although you can perform some of these tasks in a different order, BMC Software recommends using the following order.

1 Create accounts
in the OS of the systems.

2 Add the accounts


and create profiles for the systems.

Add the system and install the Distribution Client.

4 Arrange systems

in system groups.

If you performed a local installation of the Distribution Client, you register the computer with the Distribution Server, instead of adding it and installing the Distribution Client.

About accounts
Each remote computer must have a connection account and a privileged account. These accounts must already exist on the computers to which you want to connect. On Windows, both accounts should be the same account on the remote computer. You then add them to the Distribution Server using Distribution Manager. Specific account information is stored separately from the computers on the Distribution Server to make it easier to use one account for multiple remote computers. For example, if several remote computers use the same account, you could create one account for all of them and avoid having to re-type information. If the account information changes, you have to change it in only one place.

About the connection account and Distribution Client account


The connection account is used by the Distribution Server to connect to the target computer when distributing the Distribution Client. If you distribute the Distribution Client from the Distribution Server, the connection account is also used as the Distribution Client account. If you install the Distribution Client locally, you should make the connection account match the Distribution Client account specified in the local installation to avoid confusion. The Distribution Client account is used to run the Distribution Client and install distributions. For more information, see Distribution Client account on page 46.

94

Distribution Server Getting Started

About accounts

Before you distribute any products to a computer, including the Distribution Client, you must create a connection account on the computer and add it to the Distribution Server.

Connection account requirements on Windows


On Microsoft Windows platforms, BMC Software highly recommends that you use one account for all of the following accounts:
s s s

connection account Distribution Client account (Distribution Client account on page 46) privileged account (About the privileged account on page 96)

NOTE
If the Distribution Server is running on a Windows 2003 computer and you want to use Mapped Drive/Task Scheduler Service to deploy Distribution Clients, the Distribution Server account and the Distribution Client account must have the same name. For more information, see Using a mapped drive and task scheduler service (Windows only) on page 168.

The connection account must be the same account used by other BMC Software products installed in the same directory, it must be a member of the users and Administrators groups (but not the Administrator account itself), and it must have the right to connect remotely. The account can be a local or domain account. If you use a local account, enter only the account name. If you use a domain account, preface the account name with the domain. The account must have the following user rights:
s s s s

act as part of operating system increase quotas log on as a service replace a process level token

A local installation of the Distribution Client automatically assigns the previous rights to the account. Installing it from the Distribution Server, however, does not assign these rights. For a remote installation, assign these rights manually using the operating system.

Connection account requirements on UNIX


On UNIX platforms, you must use the same account for the connection account and Distribution Client account. You cannot use the same account for the privileged account because this account must be root.

Chapter 4

Using the Distribution Manager

95

About accounts

The connection account must be the same account used by other BMC Software products installed in the same directory, and it must have the right to connect remotely.

About the privileged account


This section describes the requirements of the privileged account.

NOTE
Even though the privileged account is often the same as the connection account, you must add the privileged account to properties of the computer.

Privileged account requirements on Windows


On Windows computers, BMC Software highly recommends that you use the same account for both connection and privileged accounts. This single account should meet the requirements described in Connection account requirements on Windows on page 95. However, if you must use different accounts, the privileged account must meet the following requirements:
s

Must be a member of the Administrators group, but not be the Administrators account itself. Must have the user right log on as a batch job assigned to it. Set this right in the operating system. Can be a local or domain account. If you use a local account, enter only the account name. If you a domain account, preface the account name with the domain.

Privileged account requirements on UNIX


On UNIX platforms, the privileged account must be different because it must be either root or a sudo-privileged account. It cannot be any account with its UID = 0 like root. On UNIX, the privileged account is used to install products, including the Distribution Client, when the root account is required. For details on installing and configuring sudo to create a sudo-privileged account, see Installing and configuring sudo to create a privileged account to deploy products on page 97.

96

Distribution Server Getting Started

About accounts

Installing and configuring sudo to create a privileged account to deploy products


Some PATROL products that you install will require that you enter a root account and password when you configure the products for deployment to remote computers. Instead of entering the root account and password, you can install and configure sudo, then create a sudo-privileged account and enter the sudo account and password in place of the root account and password. You must install and configure sudo before you create the product configuration.

To install and configure sudo 1 Download sudo version 1.6.7p5 or later from the following web site:
www.courtesan.com/sudo.

2 Install sudo in the /usr/local/bin directory on the Distribution Client computer. If


you install it in another location, create a link in /usr/local/bin directory to the location where sudo is installed.

3 Reconfigure sudo to turn off passsword caching by entering the following


command:
./configure --with-timeout=0

Password caching causes sudo sessions to be on a timer, meaning one sudo operation could allow multiple operations without password authentication. The installation/deployment code that is used to support sudo expects a password prompt every time sudo is invoked; therefore, password caching should be turned off for sudo to work correctly with the Distribution Server.

4 On the computer where you install sudo, enter the following lines for the User
privilege specification in the sudoers file located in the local /etc directory:
patrol ALL=PASSWD:/opt/patrol/bmc_install.sh Defaults:patrol authenticate

These entries authenticate the user. The Distribution Server always expect a password prompt when the bmc_install.sh script is invoked, so sudo must be configured to supply the password. No entries are required for the host alias, user alias, or command alias specifications.

Chapter 4

Using the Distribution Manager

97

Adding an account

Following is an example sudoers file:


#/etc/sudoers example file #Host alias specification #User alias specification #Cmnd alias specification #User privilege specification patrol ALL=PASSWD:/opt/patrol/bmc_install.sh Defaults:patrol authenticate

Adding an account
This task describes how to add an account in Distribution Manager.

Before you begin


The account must correspond to an account on the remote computer to which you want to distribute components. You can add the account in Distribution Manager before the account exists on the remote computer; however, you must create it on the remote computer before you can distribute components to that computer. For more information about account requirements, see About accounts on page 94.

To add an account 1 In the tab area, click the Systems tab. 2 In the list area, click Accounts. 3 In the list area, click the Add button. 4 Type a name for the account.
This name is used only within the Distribution Server. You might want to use a naming convention to indicate the account usage (connection account or privileged account) and the remote computer to which this account applies, as well as the user name.

5 Type the user name for the account.


If the account is a domain account, preface it with the domain name.

6 Type the password to use with this user name in both the Password box and the
Confirm Password box.

7 Click Add.

98

Distribution Server Getting Started

About profiles and directories on remote systems

About profiles and directories on remote systems


Each remote system must have a profile. A profile contains information for both installing and running the Distribution Client, including the installation directory for all BMC Software products for that system. Two of the most important parts of a profile are the installation directory and working directory. These directories cannot be changed for a system once the Distribution Client is installed on the system.
s

The installation directory is where all BMC Software products, including the Distribution Client and products that are installed locally, are installed on the system. This directory corresponds to the installation directory in a local installation. You cannot install products to different installation directories. The working directory is where the Distribution Client stores files from the Distribution Server.

WARNING
The installation directory and the working directory must be two separate directories. You cannot change either directory if the profile is used by a system with the Distribution Client installed. If you register a system with a locally installed Distribution Client, the Distribution Server might automatically create a profile for the system. For more information, see the Distribution Manager Help.

Specific profile information is stored separately from the systems to make it easier to use one profile for multiple Distribution Clients. For example, if all the profile information is the same for all Windows computers, you could create one profile for all of them and avoid having to re-type information. If the profile information changes, you have to change it in only one place.

Creating a profile
This task describes how to create a profile.

To create a profile 1 In the tab area, click the Systems tab. 2 In the list area, click Profiles. 3 In the list area, click the Add button.

Chapter 4

Using the Distribution Manager

99

About systems

4 Type a name for the profile. 5 Type the installation directory for the systems that use this profile.
This directory is the location where all components will be installed when they are distributed.

6 Type the working directory for the systems that use this profile.
This directory is the location where the installation files are stored before they are run.

7 Click Add.

About systems
A system is a remote computer to which you want to distribute components using the Distribution Server. Each system needs a connection account, privileged account, and profile. For more information about connection and privileged accounts, see About accounts on page 94. For more information about profiles, see About profiles and directories on remote systems on page 99. Before you can distribute components to a system, you must install the Distribution Client. You can install the Distribution Client locally, when you add the system, or after adding the system. To send distributions to a system, you must put the system in one or more system groups. For more information about system groups, see About system groups on page 102.

Adding systems and installing the Distribution Client


This task describes how to add systems and install the Distribution Client.

Before you begin


You must know the DNS host name or IP address of the computer that you want to add. The connection account and privileged account must be set up on the remote system and added to the Distribution Server.
100 Distribution Server Getting Started

Registering systems with locally installed Distribution Clients

A profile for the systems must already be created.

NOTE
For more information about adding systems, including importing multiple systems from a file, see the Distribution Manager Help.

To add a system and install the Distribution Client 1 In the tab area, click the Systems tab. 2 In the list area, click Systems. 3 In the list area, click the Add button. 4 In the System Name box, type the fully qualified domain name or the IP address of
the computer that you want to add.

5 If there are groups already defined, you can select a group to which you want the
system to belong. You can add the system to other groups later.

6 Select the profile, connection account, and privileged account for the system.
If the profile, connection account, or privileged account does not exist, click the corresponding New button and create it.

7 Select the Install DS Client on this system now check box.


If you do not install the Distribution Client now, you can install it later by clicking the Install DS client button on the System page.

8 Click Add. 9 To view the status of installing the Distribution Client, including any log files, view
the Distribution Status or Client Activity reports.

Registering systems with locally installed Distribution Clients


This task describes how to register systems with locally installed Distribution Clients. Registering a system tells the Distribution Server to trust the Distribution Client.

Chapter 4

Using the Distribution Manager

101

About system groups

Before you begin


The Distribution Client must be locally installed on the systems. The connection account and privileged account are already added.

To register systems automatically


From the Distribution Manager interface, choose Options=>Global Options=>Register. All added systems will be registered automatically.

To register and configure a system manually 1 In the tab area, click the Reports tab. 2 In the list area, click the System Registration report. 3 Select the systems that you want to add. 4 Click Register. 5 In the tab area, click the Systems tab. 6 In the list area, click Systems. 7 In the list area, click the name of the system. 8 Select the connection account and privileged account for the system. 9 Click Apply Changes.

About system groups


You create system groups to define the systems to which you want to install the same configuration of a collection of components. These system groups are used only within the Distribution Server. You can create multiple system groups, with overlapping members. For example, you can create one set of system groups based on operating system, another set based on applications, and another set based on computer location. For strategies for setting up system groups, see the Distribution Manager Help. A system must belong to one or more system groups in order to receive distributions.

102

Distribution Server Getting Started

Creating a system group and adding members

NOTE
If you want to distribute components to a single system by itself, create a system group that includes only that system.

Creating a system group and adding members


This task describes how to create a system group and add systems to it.

To create a system group 1 In the tab area, click the Systems tab. 2 In the list area, click System groups. 3 In the list area, click the Add button. 4 Type a name for the system group 5 Click Add. To add systems to a system group 1 In the tab area, click the Systems tab. 2 In the list area, click System groups. 3 In the list area, click system group. 4 Click the Members tab. 5 Select the systems to belong to the group and click Add. 6 Click Apply Changes.

Setting up distributions and running reports


So far you have not distributed any components (except the Distribution Client) to remote systems. The next step is to create a distribution to distribute components to remote systems. You can also run reports about systems and components.

Chapter 4

Using the Distribution Manager

103

About distributions

About distributions
A distribution is the mechanism by which you define which collections of components and associated configurations are distributed to which groups of systems, and when. A distribution includes a set of distribution items. Each distribution item identifies the following:
s s s

the collection of components to be distributed the configuration of that collection to use the system group

When you schedule a distribution, you identify when the components are distributed and the distribution mode (install, force install, or uninstall). You can schedule distributions to run immediately or on a date and time that you specify.

Setting up a distribution
This task describes how to set up a distribution.

Before you begin


Ensure that the collection of components that you want to distribute is already defined, including the configurations that you want to use. For more information, see About collections and components on page 91. Ensure that the systems to which you want to distribute the components are already added and initialized. For more information, see About systems on page 100.

To create a distribution 1 In the tab area, click the Distributions tab. 2 In the list area, click the Add button. 3 Type a name for the distribution, then click Add. 4 (optional) In the Description box, type a description of the distribution. 5 Proceed with adding distribution items.

104

Distribution Server Getting Started

Setting up a distribution

To add a distribution item 1 In the results area for the distribution, click the Items sub-tab. 2 Click Add Item. 3 Select the collection, configuration, and system group that you want to use. 4 Click Add. 5 After adding all distribution items, proceed with scheduling the distribution. To schedule a distribution 1 In the results area for the distribution, click the Schedule sub-tab. 2 Click Add Schedule. 3 Do one of the following:
s

If you want to distribute the components immediately, select Distribute Immediately. If you want to distribute the components at a later time, select Schedule Distribution, and choose the start date and time.

4 Choose the Install option.


The other modes are described in the Distribution Manager Help.

5 Click Add. 6 Once a distribution is activated, to view the status of a distribution, including any
log files, view the Distribution Status report.

Chapter 4

Using the Distribution Manager

105

About reports

About reports
On the Reports page, you can select the report that you want to run. For more information about each report, see the Distribution Manager Help.
s s s s s s s

Distribution Status Report Product Distribution Report Product Inventory Report Client Activity Report Unknown Systems Report System Reboot Report System Registration Report

NOTE
You use some reports to take actions on systems, in addition to simply viewing information. For example, you use the System Registration report to register systems which you installed the Distribution Client locally.

Running a report
This task describes how to run a report.

1 In the tab area, click the Reports tab. 2 In the list area, click the report that you want to run.

Logging off
To log off, close the browser. The Distribution Server will automatically log you off after about 15 minutes.

Where to go from here


For information about... using Distribution Manager See... Distribution Manager Help using the Distribution Server Command Appendix 5, Using the Distribution Server Line Interface Command Line Interface

106

Distribution Server Getting Started

Chapter

5
109 109 109 109 110 110 111 112 112 113 113 114 114 114 115 115 117 117 119 121 122 123 124 125 125 126 126 127 131 132
107

Using the Distribution Server Command Line Interface


5

This chapter contains information for using the Distribution Server Command Line Interface (CLI). This chapter discusses the following topics: Uses of the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Where to run the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modes for running the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Command line arguments for the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running the CLI in interactive mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running the CLI with an input file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CLI commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Typographical conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Command syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Encrypting passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Exiting interactive mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Connecting to and disconnecting from a Distribution Server . . . . . . . . . . . . . . . Managing components in the repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing systems groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing the Distribution Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing Distribution Client upgrades and removals . . . . . . . . . . . . . . . . . . . . . Managing distributions and distribution items . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing distribution schedules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing operating systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing preferences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overriding component conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 5 Using the Distribution Server Command Line Interface

Example scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Example 1: Adding systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Example 2: Distributing products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 Example 3: Uninstalling products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

108

Distribution Server Getting Started

Uses of the CLI

Uses of the CLI


The CLI provides you with the ability to administer the Distribution Server without a web browser. The CLI is useful in the following situations:
s

You cannot access the Distribution Server with a web browser, or the connection with a web browser is slow. You want to execute commands through a batch file. You want to integrate the Distribution Server with a different program.

Running the CLI


This section describes how to run the CLI.

Where to run the CLI


You can run the CLI on the computer where the Distribution Server is installed or on any remote computer with the CLI installed. However, if you are importing or exporting components, you might want to use a computer near the Distribution Server computer or on the same network. The Distribution Server cannot import from or export to a file system that is not locally accessible. The source of the import or the destination of the export must be a local drive, a mapped drive (Windows), or an NFS mounted drive (UNIX).

Modes for running the CLI


The CLI works with both an interactive mode and script (or input file) mode.
s

In interactive mode, you enter a single command and wait for completion of the command before entering another command. In script mode, the CLI reads and sequentially executes a list of commands from an input file.

Chapter 5

Using the Distribution Server Command Line Interface

109

Command line arguments for the CLI

Command line arguments for the CLI


The following table lists command line arguments for the CLI.
Argument -help or /? -v -f file -check Description This argument displays a list of help information for all arguments and commands. This argument displays program version information. This argument runs commands from a file. Use this argument in combination with the -f argument. This argument checks the file specified with the -f argument for syntax errors. The commands in the file are not executed. Use this argument in combination with the -f argument. With this argument, the execution of the commands continues, even if the specified file contains errors. This argument sets the logging level:
s s s s

-ignore_error

-d value

0=off 1=production 2=trace 3=debug

Running the CLI in interactive mode


This task describes how to run the CLI in interactive mode.

Before you begin


The Distribution Server must be running.

To run the CLI in interactive mode 1 On UNIX, perform the following steps: A Change to the $BMC_ROOT/common/bmc/ directory. B Enter the following command to set the environment variables:
./patrol7rc.sh

110

Distribution Server Getting Started

Running the CLI with an input file

2 Enter the following command at the operating system command prompt, followed
by any optional command line arguments.
dsadmin

For more information about command line arguments, see Command line arguments for the CLI on page 110.

3 To connect to a Distribution Server, enter one of the following commands:


s s

connect server_name username password econnect server_name encrypted_username encrypted_password

For more information about connecting to a Distribution Server, see Connecting to and disconnecting from a Distribution Server on page 115.

4 Enter each of the commands that you want to execute, one at a time.
For more information about the available commands, see CLI commands on page 112.

5 To disconnect from the Distribution Server, enter the following command:


disconnect

6 To exit, enter one of the following commands.


quit or exit

Running the CLI with an input file


This task describes how to run the CLI with an input file.

Before you begin


You must have a plain text file prepared with the commands that you want to execute. For more information about the available commands, see CLI commands on page 112.

NOTE
The first command in the input file must be a connect command. You can use an encrypted or unencrypted password.

Chapter 5

Using the Distribution Server Command Line Interface

111

CLI commands

To run the CLI with an input file 1 On UNIX, perform the following steps: A Change to the $BMC_ROOT/common/bmc/ directory. B Enter the following command to set the environment variables:
./patrol7rc.sh

2 Enter the following command at the operating system command prompt.


dsadmin -f file

CLI commands
This section lists the commands that you can use in the CLI.

Typographical conventions
The following conventions are used in this section:
s

Text in italics represents a variable, as shown in the following examples: The table table_name is not available.
system/instance/file_name

Items enclosed in braces ( { } ) and separated by a vertical bar ( | ) indicate that you must choose one item. (Do not type the braces or vertical bar.) In the following example, you would choose a, b, or c: { a | b | c }

An ellipsis ( . . . ) indicates that you can repeat the preceding item or items as many times as necessary. You must separate each item with spaces. Square brackets ( [ ] ) around an item indicate that the item is optional. (Do not type the brackets.)

112

Distribution Server Getting Started

Command syntax

Command syntax
This section describes the command syntax for the Distribution Server Command Line Interface.

Case sensitivity
Commands and options are case-insensitive. However, names of items, such as collections and distributions, are case-sensitive.

EXAMPLE
The commands collection add mycollection and Collection ADD mycollection do the same thing, but the command collection add MyCollection adds a different collection.

Text strings
Enclose text strings with spaces, such as labels, in double-quotes.

EXAMPLE
collection add my collection

Comment lines
Type the # character as the first non-space character in a line to indicate a comment line.

EXAMPLE
# This is a comment.

Getting help
Command help [command] Description This command displays a list of help information for all commands. If you specify a command, this command displays detailed help for that command.

Chapter 5

Using the Distribution Server Command Line Interface

113

Encrypting passwords

Encrypting passwords
Several commands take encrypted passwords as command arguments. You use the following command to encrypt a plain text password.
Command util encrypt string_to_encrypt Description This command displays the value in string_to_encrypt as an encrypted string. You can use this command to encrypt a password to use in a CLI batch file.

Using aliases
You can create aliases for commands to map commands to names of your choosing. Aliases have the following properties:
s

You can create an alias for any command, including command arguments. The alias must be the first item on the line where it is used. You can use only one alias per line. Aliases are case-sensitive. Aliases are valid for only the current session or script. Once you exit the Distribution Server Command Line Interface, all aliases are lost.
Description This command adds the alias for the specified command. This command removes the specified alias. This command lists the existing aliases.

Command alias add alias_name command alias remove alias_name alias list

Exiting interactive mode


Command { quit | exit } Description This command exits the Distribution Server Command Line Interface.

114

Distribution Server Getting Started

Connecting to and disconnecting from a Distribution Server

Connecting to and disconnecting from a Distribution Server


NOTE
You can connect to only one Distribution Server at a time. You must specify the host name of the Distribution Server, not the IP address or the fully qualified domain name. If the host name of the Distribution Server has changed, use the host name of the computer when the Distribution Server was installed.

Command connect server_name username [password]

Description This command connects to the specified Distribution Server with the specified username and password. If you omit the password when running interactively, you will be prompted for it.

econnect server_name encrypted_username This command connects to the specified Distribution Server with encrypted_password the encrypted username and encrypted password. See Encrypting passwords on page 114 for information about how to encrypt a password. disconnect This command disconnects from the current Distribution Server.

Managing components in the repository


NOTE
A component might have multiple packages listed when you use the component listimage or component list commands, depending on the platforms available and how the component was packaged. However, when you view the same component in Distribution Manager, all of the packages are merged into one item. When importing such a component using the CLI, import all packages listed for the component, unless you know that you will not need them for your environment. When you view the component in Distribution Manager, you will not be able to tell if only some packages were imported using the CLI.

Chapter 5

Using the Distribution Server Command Line Interface

115

Managing components in the repository

Command component setsourcedir image_location [-user username encrypted_password]

Description This command sets the location of the product directories for import. You must execute this command prior to importing components. The -user flag with the user name and encrypted password are required when the Distribution Server is run as a service on a Windows computer. See Encrypting passwords on page 114 for information about how to encrypt a password.

component setdestdir destination_directory

This command sets the destination directory for export. You must execute this command prior to exporting components. This command lists all selectable components on the image. This command lists all selectable components in the repository.
s

component listimage component list [-invalid] [-inactive]

If the -invalid flag is set, only invalid components are listed. If the -inactive flag is set, only inactive components are listed.

component import ppf_name [-nowait] component export ppf_name:ppf_version [:ppf_revision][-nowait]

This command imports the ppf and all dependencies from the source directory. Use the -nowait flag to execute the command asynchronously. This command exports the ppf and all dependencies to the destination directory. The ppf_revision is the revision number. In rare cases, a component has a revision because at least one other component has the same name and version. For more about revisions, see the Distribution Manager Help. Use the -nowait flag to execute the command asynchronously. This command removes the component and all dependencies. The ppf_revision is the revision number. In rare cases, a component has a revision because at least one other component has the same name and version. For more about revisions, see the Distribution Manager Help. Use the -nowait flag to execute the command asynchronously. This command makes a component inactive, which means you cannot add it to a collection. Also the component list command does not display inactive components by default. You can undo this command with the component reactivate command. For more information about inactive components, see the Distribution Manager Help. This command turns an inactive component into an active component. Reactivate an inactive component when you need to add it to a collection.

component remove ppf_name:ppf_version [:ppf_revision][-nowait]

component deactivate ppf_name:ppf_version [:ppf_revision]

component reactivate ppf_name:ppf_version [:ppf_revision]

116

Distribution Server Getting Started

Managing collections

Managing collections
Command collection add collection_name [-des description] collection modify collection_name [-ren collection_name] [-des description] collection remove collection_name collection list collection addcomp collection_name ppf_name:ppf_version[:ppf_revision] [] Description This command adds a new collection and optionally defines its description. This command modifies the name of the specified collection, its description, or both. This command removes the specified collection. This command lists all collections. This command adds one or more components to an existing collection. The ppf_revision is the revision number. In rare cases, a component has a revision because at least one other component has the same name and version. For more about revisions, see the Distribution Manager Help. This command removes one or more components from an existing collection. The ppf_revision is the revision number. In rare cases, a component has a revision because at least one other component has the same name and version. For more about revisions, see the Distribution Manager Help. This command displays the collection name, description, the selectable components in the collection, and configurations. This command updates any hidden components in a collection that may have previously been missing from the repository, but which are now available This command copies the specified collection to a new collection. You can optionally copy all configurations to the new collection and set the description for the new collection.

collection removecomp collection_name ppf_name:ppf_version[:ppf_revision] []

collection info collection_name

collection refresh collection_name

collection copy collection_name newcollection_name [-cfg] [-des description]

Managing configurations
Command configuration add configuration_name collection_name [-des description] configuration modify configuration_name collection_name [-ren configuration_name] [-des description] Description This command adds a new configuration for the specified collection, and optionally sets its description. All answers to the questions of this collection are set to the default value. This command modifies the name of the specified configuration, its description, or both.

Chapter 5

Using the Distribution Server Command Line Interface

117

Managing configurations

Command configuration remove configuration_name collection_name configuration list collection_name configuration info configuration_name collection_name configuration interview configuration_name collection_name [-ques question_name value] [] [-uninstall]

Description This command removes the specified configuration. This command lists all configurations for the specified collection. This command displays the configuration name, collection name, description and all configuration variables and answers. This command performs the interview for a configuration. You will be prompted for values for each question in the configuration. When the CLI displays the configuration questions, it does not remove the HTML tags that are used to present the question in the Distribution Server GUI. Disregard the HTML tags. If you use the -ques flag, this command sets the answer to the specified questions. Use the configuration info command to find the names of the questions you want to answer with the -quest flag. Use the -uninstall flag to answer questions associated with uninstalling the components.

configuration copy configuration_name collection_name new_configuration_name [-col collection_name] [-des description]

This command copies the specified configuration to a new configuration and optionally sets its description. The new configuration will belong to the same collection as the original configuration, unless a different collection is specified.

118

Distribution Server Getting Started

Managing systems

Command configuration setdestdir destination_directory configuration export configuration_name collection_name os [] [-expin] [-idir installation_directory] [-nowait] [-role [managed],[console], [common],[role_string]]

Description This command sets the existing destination directory for export. This command exports the specified configuration to the destination directory. For a list of operating systems known to the Distribution Server, see Managing operating systems on page 126. If expin (exportinstaller) is set, the installation engine is also exported. Use the -idir flag to set the installation directory in the exported control file. Use the -nowait flag to execute the command asynchronously. Use the -role flag to export packages meant for specified roles.

Managing systems
Command system add system_name [] [-prof profile_name] [-cacct connection_account] [-pacct privileged_account] [-group group_name] Description This command adds one or more systems, defining the following:
s s s

the profile for the systems the accounts for the systems the group the system(s) will be member of (optional)

The system_name can be the DNS name or an IP address. system import path_and_file_name [-prof profile_name] [-cacct connection_account] [-pacct privileged_account] [-group group_name] This command imports one or more systems from a file, defining the following:
s s s

the profile for the systems the accounts for the systems the group the systems will be members of (optional)

The system_name can be the DNS name or an IP address. system remove system_name [] system list [-group group_name] This command removes one or more systems. This command lists all known systems. Use the -group flag to list only systems in the given group.

Chapter 5

Using the Distribution Server Command Line Interface

119

Managing systems

Command system info system_name [] system modify system_name [-ren system_name] [-grpadd group_name []] [-grprem group_name []] [-prof profile_name] [-cacct connection_account] [-pacct privileged_account] [-dns dns_name] [-wins wins_name] [-infrole role []] [-loc locale1 []] [-rboot { yes|no | inherit } ] [-trusted { yes | no } ] [-pushmode <yes | no>] [-siteid <site_id>]

Description This command displays the properties of the specified systems. This command modifies the properties of the system.
s s s s s s s s s s s s

The -ren flag renames the system label. The -grpadd flag adds the system to one or more groups. The -grprem flag removes the system from one or more groups. The -prof flag defines the profile the system uses. The -cacct flag defines the connection account the system uses. The -pacct flag defines the privileged account the system uses. The -dns flag sets the DNS name. The -wins flag sets the WINS name. The -infrole flag sets one or more infrastructures roles. The -loc flag sets one or more locales. The -trusted flag defines the system as trusted or not trusted. The -pushmode flag determines whether files are pushed from the DS server (yes) or pulled from DS client (no). This flag is applicable only for VMS/Alpha systems. The -siteid flag defines the site ID number for the VMS cluster. This flag is applicable only for VMS/Alpha systems.

system setattribute system_name [Country: value ] [City: value ] [Building: value ] [Floor: value ] [OfficeLocation: value ] [Category: value ] system proddisc system_name []

This command sets the value for one or more system attributes.

This command initiates product discovery for the specified systems.

120

Distribution Server Getting Started

Managing systems groups

Managing systems groups


Command sysgroup add group_name [-des description] sysgroup modify group_name [-ren group_name] [-des description] [-sysadd system_name []] [-sysrem system_name []] sysgroup remove group_name [] sysgroup info group_name [] sysgroup list sysgroup setdestdir destination_directory Description This command adds a new system group, and optionally sets its description. This command modifies an existing system group. You can rename the group, change its description, add systems to it, and remove systems from it.

This command removes one or more system groups. This command lists the group name, description, profile, connection account, and the group members. This command lists all system groups. This command sets the destination directory for export. If the destination directory is not set, the current directory is used. Note, this is a directory on the local system, not necessarily on the Distribution Server. This command exports the group and member systems to the specified file in the destination directory. By default the file is overwritten. To append to the file, use the -f flag. This command imports the group and member systems from the specified file in the destination directory. Note, this is a directory on the local system, not necessarily on the Distribution Server. This command initiates product discovery for the systems in the specified system groups.

sysgroup export group_name [] -f file_name [-f app] sysgroup import path_and_file_name

sysgroup proddisc group_name []

Chapter 5

Using the Distribution Server Command Line Interface

121

Managing accounts

Managing accounts
Command account add account_name user_name password password_confirmation [-encrypted] Description This command adds a new account. If the account will not have a password, you can use as a null value in the password and the password_confirmation fields. For example, account add TestAcc user1 adds the account TestAcc with no password information. The -encrypted flag indicates that the password and the password confirmation are encrypted. See Encrypting passwords on page 114 for information about how to encrypt a password. This command modifies the properties of an account. account modify account_name [-ren account_name] [-user user_name password password_confirmation The -ren flag renames the account. [-encrypted]] If the account does not have a password, use as a null value in the password and the password_confirmation fields. The -encrypted flag indicates that the password and the password confirmation are encrypted. See Encrypting passwords on page 114 for information about how to encrypt a password. account remove account_name account list This command removes the specified account. This command lists all defined accounts, including their user names.

122

Distribution Server Getting Started

Managing profiles

Managing profiles
Command profile add profile_name inst_dir cache_dir [-dslist ds_server1 []] [-rboot {yes | no | inherit} ] [-autostart { yes | no } ] [-ctout MM] [-thres # # ] [-runct HH:MM] [-runch MM] [-cache cachedays_# # cachesize_# # ] [-cport # # ] [-aport # # ] [-httpto # # # ] Description This command adds a new profile.
s s s s s s

s s s s s s

The inst_dir and cache_dir are the installation (BMC root) directory and Distribution Client working directories. The -dslist flag specifies a list of valid distribution servers. The -rboot flag sets the system reboot flag. (Windows only) The -autostart flag specifies whether the Distribution Client restarts when the system reboots. (UNIX only) The -ctout flag sets the connection time-out. The -thres flag sets the maximum number of times the Distribution Client will attempt to retrieve a file from the Distribution Server. The -runct flag is used when the Distribution Client is run daily. It defines the start time for the Distribution Client. The -runch flag defines in minutes how often the Distribution Client will check for distributions. The -cache flag defines how long packages stay in the cache after an unsuccessful deployment and the cache size in MB. The -cport flag defines the port the Distribution Server uses to ping the Distribution Client. The -aport flag defines the port used by the PATROL Agent, if any, on the system. The -httpto flag defines the time in seconds that the Distribution Client will wait for a response from the Distribution Server.

The ds_hostprofile.mof file contains the default values for the optional fields.

Chapter 5

Using the Distribution Server Command Line Interface

123

Installing the Distribution Client

Command profile modify profile_name [-ren profile_name] [-idir inst_dir ] [-cdir cache_dir] [-dslist ds_server1 []] [-rboot { yes | no | inherit }] [-autostart { yes | no } ] [-ctout MM] [-thres # # ] [-runct HH:MM] [-runch MM] [-cache cachedays_# # cachesize_# # ] [-cport # # ] [-aport # # ] [-httpto # # # ] profile remove profile_name profile info profile_name profile list

Description This command modifies the specified profile.


s s s

The -ren flag renames the current profile. The -idir flag sets the installation directory (BMC root). the -cdir flag sets the cache directory.

For a description of the flags that are in both this command and in the profile add command, see the profile add command. Only the fields you specify are updated. The other fields retain their current value.

This command removes the specified profile. This command displays the properties of the profile. This command lists all profiles.

Installing the Distribution Client


Command initialize start description [ -system system_name [] ] [ -sysgroup group_name [] ] [-pdisc] [-nowait] [-force] Description This command discovers and initializes one or more systems or system groups. Use the -pdisc flag to launch product discovery on the system and update the host inventory. An ID for the initialization is printed in an informational message. Use the -nowait flag to execute the command asynchronously. Use the -force flag to force a new initialization for systems which already have an initialization in progress. initialize list initialize stop init_ID This command lists all active initialization operations, including the init ID and systems or system groups. This command stops the specified initialization.

124

Distribution Server Getting Started

Managing Distribution Client upgrades and removals

Managing Distribution Client upgrades and removals


Command dsc upgrade group_name ppf_name:ppf_version YYYY-mm-dd HH:MM dsc remove group_name [-nowait] Description This command installs the specified version of the Distribution Client on all systems in the specified group at the specified start date and time. This command removes the Distribution Client from all systems in the specified group. Use the -nowait flag to execute the command asynchronously. dsc list This command lists all available versions of the Distribution Client.

Managing distributions and distribution items


Command dset add distribution_name [-des description] [-installopts options ] dset remove distribution_name dset modify distribution_name [-ren name] [-des description] [-installopts options ] dset list dset info distribution_name dset validate distribution_name Description This command adds a new distribution, and optionally sets its description. Use the -installopts flag to pass options to the installer. This command removes the specified distribution. This command modifies an existing distribution.

This command lists all distributions. This command displays the distribution name, description and all distribution items. This command validates a distribution. Any warnings/errors are displayed at the command line. See Distribution Manager Help for more information about validating distributions.

dset additem distribution_name This command adds one or more distribution items to group_name :collection_name: configuration_name [] the specified distribution. A distribution item ID is returned. dset removeitem distribution_name group_name :collection_name: configuration_name This command removes a distribution item from the specified distribution.

Chapter 5

Using the Distribution Server Command Line Interface

125

Managing distribution schedules

Managing distribution schedules


Command deployment add distribution_name YYYY-MM-DD HH:MM [-mode {install | forceinstall | uninstall } ] Description This command schedules a distribution, including the start date, start time, and optionally the mode. To schedule the distribution at a time relative to the current time, set YYYY-MM-DD to 0000-00-00, and set HH:MM to the elapse time. The deployment ID is returned. deployment remove distribution_name deployment_ID deployment modify distribution_name deployment_ID [-sdate YYYY-MM-DD HH:MM] [-mode {install | forceinstall | uninstall } ] This command removes the specified distribution schedule. This command modifies the specified schedule. To schedule the distribution at a time relative to the current time, set YYYY-MM-DD to 0000-00-00, and set HH:MM to the elapse time. You cannot modify an active deployment. deployment cancel distribution_name deployment_ID This command cancels the specified distribution schedule. deployment list [-dset distribution_name] This command lists all scheduled distributions. To list schedules for only a specific distribution, use the -dset flag.

Managing operating systems


Command os list Description This command lists all the operating systems known to the Distribution Server. You can use these OS values when exporting a configuration. See Managing configurations on page 117.

126

Distribution Server Getting Started

Managing reports

Managing reports
Command report setdestdir destination_directory report deployactive distribution_name start_timestamp [-f file_name] [-csv] Description This command sets the destination directory for output to file. If not set, the current working directory is used. This command displays a report on the activity of the specified distribution, including
s s s s s

system name deployment state status message progress distribution and installation log file location

This report corresponds to the active tab of the Distribution Status report in Distribution Manager. The format for the start_timestamp variable is: yyyymmddhhmmss.xxxxxxsyyy where: s yyyy is year s mm is month s dd is day s hh is hour s mm is minute s ss is second s xxxxxx is microseconds (always 000000 within the Distribution Server) s s is either a + or - to indicate the direction of the local offset from GMT s yyy is local offset from GMT Use the -f flag to write the report to the specified file in the destination directory. If the file exists, it is overwritten. Use the -csv flag to format the report as a list of comma separated values.

Chapter 5

Using the Distribution Server Command Line Interface

127

Managing reports

Command

Description

report deployhist distribution_name start_timestamp This command displays a report on the history of the [-f file_name] specified deployment, including [-csv] s system name s deployment start and end times s deployment state s total number of packages deployed s total package size s distribution and installation log file location This report corresponds to the history tab of the Distribution Status report in Distribution Manager. The format for the start_timestamp variable is: yyyymmddhhmmss.xxxxxxsyyy where: s yyyy is year s mm is month s dd is day s hh is hour s mm is minute s ss is second s xxxxxx is microseconds (always 000000 within the Distribution Server) s s is either a + or - to indicate the direction of the local offset from GMT s yyy is local offset from GMT Use the -f flag to write the report to the specified file in the destination directory. If the file exists, it is overwritten. Use the -csv flag to format the report as a list of comma separated values.

128

Distribution Server Getting Started

Managing reports

Command report prodsbysystems group_name [ {detail | summary } ] [-f file_name] [-csv]

Description This command displays a report on the products deployed on the systems in the specified system group. The summary report includes
s s s s

product description package name product version number of products installed

The detailed report includes


s s s s

system name product description product version package name

Use the -f flag to write the report to the specified file in the destination directory. If the file exists, it is overwritten. Use the -csv flag to format the report as a list of comma separated values. report prodsdeployed ppf_name [] [-group group_name ] [ { detail | summary } ] [-f file_name] [-csv] This command displays a report on the specified products deployed for all systems (default) or a specified group. The summary report displays: s product description s package name s product version s number of installations The detailed report displays s product description s system name s product version s package name This report corresponds to the Product Distribution report in Distribution Manager. Use the -f flag to write the report to the specified file in the destination directory. If the file exists, it is overwritten. Use the -csv flag to format the report as a list of comma separated values.

Chapter 5

Using the Distribution Server Command Line Interface

129

Managing reports

Command report sysunknown group_name [-init] [-f file_name] [-csv]

Description This command displays a report on the systems in a group that are either not discovered or not initialized. This report corresponds to the Unknown Systems report in Distribution Manager. If -init is set and discovery is successful, the system is initialized. Use the -f flag to write the report to the specified file in the destination directory. If the file exists, it is overwritten. Use the -csv flag to format the report as a list of comma separated values.

report proddisc { -system system_name [] | -sysgroup group_name [...] } [-f file_name] [-csv] [-reminvent ]

This command displays a report with the results of product discovery on the specified systems. This report corresponds to the Product Inventory report in Distribution Manager. Use the -f flag to write the report to the specified file in the destination directory. If the file exists, it is overwritten. Use the -csv flag to format the report as a list of comma separated values. Use the -reminvent flag to remove entries from the product inventory that are listed as missing on this report. Missing inventory items are products that are listed in the inventory, but not found during product discovery. These components were probably uninstalled locally.

report initactive init_ID [-f file_name] [-csv]

This command displays a report on the initialization status of all hosts for the specified initialization ID. This report corresponds to the Client Activity report in Distribution Manager. Use the -f flag to write the report to the specified file in the destination directory. If the file exists, it is overwritten. Use the -csv flag to format the report as a list of comma separated values.

130

Distribution Server Getting Started

Managing preferences

Command report sysreg [-register system_name [ ] ] [-f file_name ] [-csv]

Description This command displays a report on all systems waiting to be registered with the Distribution Server. This report corresponds to the System Registration report in Distribution Manager. The -register flag registers the systems with the Distribution Server. Use the -f flag to write the report to the specified file in the destination directory. If the file exists, it is overwritten. Use the -csv flag to format the report as a list of comma separated values.

report sysreboot [-rboot system_name [] ] [-f file_name ] [-csv]

This command displays a report on all systems that require a reboot after the installation process is complete. This report corresponds to the System Reboot report in Distribution Manager. The -rboot flag reboots the specified systems. Use the -f flag to write the report to the specified file in the destination directory. If the file exists, it is overwritten. Use the -csv flag to format the report as a list of comma separated values.

Managing preferences
Command privilege add usergroup privilege [] Description This command adds one or more privileges to the specified user group. For a list of privileges, use the help privilege command. privilege remove usergroup privilege [] This command removes one or more privileges from the specified user group. For a list of privileges, use the help privilege command.

Chapter 5

Using the Distribution Server Command Line Interface

131

Overriding component conflicts

Command privilege list [usergroup] ds setglobal [-rboot { yes | no } ] [-depnc # # ] [-llog { yes | no } ] [-uplog { yes | no } ] [-remlogs dd] [-areg { yes | no } ] [-trace { yes | no } ] [-reminvent { yes | no } ] [-protocols protocol_1,protocol_2protocol_n] [-cleanuptime hh:mm]

Description This command lists the privileges assigned to the specified usergroup or to all usergroups if no group is specified. This command sets global Distribution Server options.
s

The -rboot flag sets the global system reboot flag. (Windows only) The default is no. The -depnc flag sets the number of Distribution Clients the Distribution Server deploys to in parallel during a deployment session. The -llog flag defines whether a localized log file will be generated in addition to the English log file. The -uplog flag defines if the log files get uploaded from the Distribution Client to the Distribution Server if the installation was successful. The -remlogs flag removes log files after the specified number of days. The -areg flag controls whether incoming Distribution Client registration requests are automatically approved. The -trace flag defines if the Distribution Server will operate in trace mode. The -reminvent flag determines whether the Distribution Server automatically removes entries from the product inventory that are listed in the inventory, but not found during product discovery. These components were probably uninstalled locally. The -protocols flag sets the methods for installing the Distribution Client. The options for protocol are windows, sftp, ftp, and agent. You can use as few as one or as many as all protocols. This flag is the same as set install method in the Distribution Manager. See About installation methods for distributing the Distribution Client on page 166. The -cleanuptime flag sets the time of day that you want the Distribution Server cleanup task to begin.

Overriding component conflicts


This command allows you to solve a component conflict. See Component conflict overrides on page 83.

132

Distribution Server Getting Started

Example scripts

Command coverride update override_file

Description This command allows you to upload an override file for a component conflict. A component conflict prevents you from putting two or more components in the same collection.

Example scripts
This section contains example scripts for the Distribution Server Command Line Interface.

Example 1: Adding systems


The following example script sets up the accounts, profiles, systems, and system groups. It distributes the Distribution Client to the systems and adds the systems to system groups.

################################################################## # Subject : Distribution Server # Description: This file performs a system PI of clients # assigned to DS # # MyServer : the DS server being used # MySolaris : a Solaris client machine # MyWindows : a Windows client machine # MyLinux : a Linux client machine ################################################################## ################################################################## # Connect to DS server ################################################################## connect MyServer MyServerAcct MyServerPasswd ################################################################## # Create Connection accounts ################################################################## account add "MySolaris connection account" SolarisAcct SolarisPasswd SolarisPasswd account add "MyWindows connection account" WinAcct WinPasswd WinPasswd account add "MyLinux connection account" LinuxAcct LinuxPasswd LinuxPasswd ################################################################## # Create Privilege accounts Chapter 5 Using the Distribution Server Command Line Interface 133

Example 1: Adding systems

################################################################## account add "MySolaris priv account" root SolarisRootPasswd SolarisRootPasswd account add "MyWindows priv account" WinAcctWithAdminPrivs AcctPasswd AcctPasswd account add "MyLinux priv account" root LinuxRootPasswd LinuxRootPasswd ################################################################## # Create profiles ################################################################## profile add "MySolaris profile" /apps2/home/patroli/DSClient /apps2/home/patroli/DSClient/cache -cport 50005 profile add "MyWindows profile" C:\DSClient C:\DSClient\cache -cport 50005 profile add "MyLinux profile" /usr/patroli/DSClient /usr/patroli/DSClient/cache -cport 50005 ################################################################## # Add systems ################################################################## system add MySolaris.bmc.com -cacct "MySolaris connection account" -pacct "MySolaris priv account" -prof "MySolaris profile" system add MyWindows.bmc.com -cacct "MyWindows connection account" -pacct "MyWindows priv account" -prof "MyWindows profile" system add MyLinux.bmc.com -cacct "MyLinux connection account" -pacct "MyLinux priv account" -prof "MyLinux profile" ########################################## # Start PI ########################################## initialize start "System Initialization" -system MySolaris.bmc.com initialize start "System Initialization" -system MyWindows.bmc.com initialize start "System Initialization" -system MyLinux.bmc.com ########################################## # Add systems to system groups ########################################## sysgroup add Windows sysgroup add UNIX sysgroup modify Windows -sysadd MyWindows.bmc.com sysgroup modify UNIX -sysadd MySolaris.bmc.com sysgroup modify UNIX -sysadd MyLinux.bmc.com disconnect exit

134

Distribution Server Getting Started

Example 2: Distributing products

Example 2: Distributing products


The following example script sets up and kicks off a distribution to the system groups added in Example 1: Adding systems on page 133. It assumes that you have already imported the components and set up collections and configurations.

################################################################## # Subject : Distribution Server Testing Environment Setup # Description: This file imports and distributes the PATROL agent # # Windows system group: Windows # Windows collection: coll_nt_agent # Windows configuration: Windows_agent_inst # UNIX system group: UNIX # UNIX collection: coll_unix_agent # UNIX configuration: Unix_agent_inst ################################################################## ################################################################## # Connect to DS server ################################################################## connect MyServer MyServerAcct MyServerPasswd ########################################## # Create a distribution set ########################################## dset add Deploy_Agent_Set ################################################# # Add a distribution item to distribution set ################################################# dset additem Deploy_Agent_Set "Windows:coll_nt_agent:Windows_agent_inst" dset additem Deploy_Agent_Set "Unix:coll_unix_agent:Unix_agent_inst" ################################################# # Schedule deployment ################################################# deployment add Deploy_Agent_Set 0000-00-00 00:00 ########################################## # Disconnect ########################################## disconnect exit

Chapter 5

Using the Distribution Server Command Line Interface

135

Example 3: Uninstalling products

Example 3: Uninstalling products


The following example script kicks off an uninstallation of the PATROL Agent distribution done in Example 2: Distributing products on page 135. It assumes that you have already answered the uninstallation questions for the configuration.

################################################################## # Subject : Distribution Server Testing Environment Setup # Description: This file uninstalls the PATROL Agent ################################################################## ########################## # Connect to DS server ########################## connect MyServer MyServerAcct MyServerPasswd ################################################### # Schedule the distribution set in uninstall mode ################################################### deployment add Deploy_Agent_Set 0000-00-00 00:00-mode uninstall ############## # Disconnect ############## disconnect exit

136

Distribution Server Getting Started

Chapter

6
138 138 138 139 139 139 139 139 140 140 142 142 143 143 144 145

Using pkgcreate
This chapter explains the pkgcreate program by showing the uses of this program, the package creation process, and the pkgcreate command arguments. The following topics are discussed: Packaging custom components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pkgcreate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Custom import feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PATROL Package Format (PPF) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Support for pkgcreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running pkgcreate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Where to run pkgcreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running pkgcreate on UNIX systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running pkgcreate on Windows systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Argument descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Source directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Destination directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Minimum required arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying destination directory and operating system . . . . . . . . . . . . . . . . . . . . Importing the package into the Distribution Server . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 6

Using pkgcreate

137

Packaging custom components

Packaging custom components


Packaging is the process of creating installation files that are compatible to the Distribution Server or BMC Software installation utility. Packaging is a required step before importing a component into the Component Repository of the Distribution Server. If you have written a PATROL Knowledge Module, you can package this custom component with the pkgcreate utility or the custom import feature in the Distribution Manager.

pkgcreate
pkgcreate is a command line interface program for advanced users, and it provides

many options that affect how the Distribution Server handles a custom component. After using pkgcreate, import your package into the Component Repository of the Distribution Server with the standard import feature in the Distribution Manager or Distribution Server Command Line Interface. This chapter describes how to use pkgcreate.

NOTE
You might also find the PPFExtract and PPFCompress utilities helpful in packaging custom components. See the PATROL Command Line Interfaces Reference Manual.

Custom import feature


The custom import feature in the Distribution Manager is well suited to novice users of the Distribution Server because it is easy to use, but has more limitations than pkgcreate. As for ease of use, the custom import has a graphical interface that guides users through the packaging process. Users also do not need to understand how to import a component into the repository because the custom import automatically performs this task. As for limitations, the custom import can only import components that work with PATROL 3.x products; use pkgcreate to package custom components for PATROL 7.x products. The custom import also provides fewer packaging options than pkgcreate. For more information about the custom import, see the Distribution Manager Help.

138

Distribution Server Getting Started

PATROL Package Format (PPF)

PATROL Package Format (PPF)


When you run pkgcreate, it creates a PATROL package format file, or .ppf file, and a set of compressed files from the custom files. The .ppf file describes the contents of the compressed files and it provides the information the Distribution Server needs to successfully extract and deploy the custom files.

Support for pkgcreate


When calling BMC Software Customer Support for help with pkgcreate, please keep in mind that our support representatives cannot assist you with issues that result from the design of a custom KM. The purpose of pkgcreate is to package files in a form that you can import into the Distribution Server. If pkgcreate successfully completes this objective and the Distribution Server places the package onto the Distribution Client, our support representatives cannot help you with other issues that relate to your custom KM.

Running pkgcreate
This section describes how to run pkgcreate.

Where to run pkgcreate


You can run pkgcreate on any computer where the Distribution Server is installed.

Running pkgcreate on UNIX systems


This task describes how to run pkgcreate on UNIX systems.

To run pkgcreate on a UNIX system 1 Change to the $BMC_ROOT/common/bmc/ directory. 2 Enter one of the following commands to set the environment variables:
s

for sh, ksh, or bash shell, enter


. ./patrol7rc.sh

Chapter 6

Using pkgcreate

139

Running pkgcreate on Windows systems

for csh or tcsh shell, enter


source ./patrol7rc.csh

3 Enter the following command at the operating system command prompt, followed
by the command arguments:
pkgcreate

For more information about command arguments, see Argument descriptions on page 140.
pkgcreate creates the .ppf file and the compressed files in the destination directory.

For more information about the files and directories that are created, see Destination directory on page 142.

Running pkgcreate on Windows systems


This task describes how to run pkgcreate on Windows systems.

To run pkgcreate on a Windows system 1 Open a command window. 2 Enter the following command at the operating system command prompt, followed
by the command arguments:
pkgcreate

For more information about command arguments, see Argument descriptions on page 140.
pkgcreate creates the .ppf file and the compressed files in the destination directory.

For more information about the files that are created, see Destination directory on page 142.

Argument descriptions
In this section, each argument is described in detail, including its syntax and options. The typographic conventions used in this section are described in Typographical conventions on page 112.

140

Distribution Server Getting Started

Argument descriptions

Table 1 presents a description for each argument for the pkgcreate command. Table 1
Argument -p productname -fs source_path

Command Arguments for pkgcreate


Description Required unless you are using the -h or -v arguments. Specifies the name of the product and the ppf file. Required unless you are using the -h or -v arguments. Specifies the location of the files you want to package. See Source directory on page 142 for more information. Optional. Specifies the directory where the packaged files will be placed. The default is the current working directory. See Destination directory on page 142 for more information. Optional. Specifies the product family. The default is PATROL. If -pd is used, then -pf is required. Optional. Specifies the product directory, the directory under which the files contained in the generated package will be installed. The default is Patrol3. If -pf is used, then -pd is required. Optional. Specifies the product version number. The default is 1.1.00 Optional. Specifies the product book name. The default is Patrol Knowledge Modules. The book is the highest level grouping for the products. Optional. Specifies the package description. The default is product Custom Package. Optional. Specifies the list of valid operating systems. The default is all. To specify more than one operating system, separate the names by commas. Optional. Specifies the products to display during the installation. The default is 3.5, 7.2 Optional. Specifies the size of package files before they are compressed. The default is 0. Optional. Specifies the size of the compressed file. The default is 0. Optional. Lists the product codes for the infrastructure components that must be installed for the package to be successfully installed. The default is no code. Separate multiple codes with commas. Optional. Specifies the packages role within the infrastructure core components. The default is no code. Provide only one value. Optional. Specifies a temporary working directory. Required if the destination directory set by -fd is the same or a subset of the source directory set by -fs. There is no default. See Destination directory on page 142 for more information. Optional. Specifies that if the product directory and product.ppf file already exist, pkgcreate overwrites them without further confirmation. If -force_new is not set, pkgcreate will ask for confirmation before overwriting the existing files. Optional. Displays Help text. Cannot be combined with any other argument. Optional. Displays version information for pkgcreate. Cannot be combined with any other argument.

[-fd destination_path]

[-pf product_family] [-pd product_directory]

[-z version] [-b book] [-d description] [-o oslist] [-r releasever] [-s pkgsize] [-c pkgcsize] [-id infrastruct_designator]

[-ir infrastruct_role] [-wd temp_dir]

[-force_new]

[-h] [-v]

Chapter 6

Using pkgcreate

141

Source directory

Source directory
The source directory contains the files you want to package using pkgcreate. You specify the source directory by using the -fs argument. You must specify an absolute path to the source directory. pkgcreate will not recognize a relative path. pkgcreate gathers the custom files from the source directory and preserves the existing subdirectories. When the Distribution Server deploys the package, the files are placed in the installation directory in the same subdirectory structure. For example, if the test.km file is located in the $Source_Directory/lib/knowledge directory when pkgcreate is run, and Patrol3 is selected as the installation directory when the package is distributed by Distribution Server, then the Distribution Server places the test.km file in the $BMC_ROOT/Patrol3/lib/knowledge directory.

Destination directory
When pkgcreate creates a package, it places all the package files in the destination directory. It uses two subdirectories of the destination directory, the Index directory and the Product directory. If these two directories do not exist, pkgcreate creates them. pkgcreate then creates a subdirectory in the Product directory with the productname you specified with the -p argument.
pkgcreate compresses the files from the source directory, places them in the productname directory, and adds the filenames to the Files section of the .ppf file. pkgcreate places a copy of the .ppf file in the Index subdirectory and places the .ppf file, the .xml file, the .cat file, and all the .gz files in the productname subdirectory.

As a default, pkgcreate uses the current directory as the destination directory. However, you can specify a different directory as the destination directory by using the -fd argument. If you do use the -fd argument you must specify the absolute path to the directory. pkgcreate will not recognize a relative path. If the destination directory is the same as the source directory, or if it is a subdirectory of the source directory, pkgcreate needs a temporary directory to work in. You must specify the temporary directory with the -wd argument.

142

Distribution Server Getting Started

Examples

Examples
Minimum required arguments
This example shows the most basic pkgcreate command and parameters. Only the two required parameters, -p and -fs, are specified. All the other ppf file parameters are assigned by default.

Command:
pkgcreate -p mytest -fs C:\temp\mytestfiles

Results
If the Index and Products directories do not already exist in your current directory, pkgcreate creates them. Then pkgcreate creates the mytest directory as a subdirectory of the Products directory. pkgcreate places a copy of the newtest.ppf file in both the Index and the Products/mytest directories. pkgcreate places several .gz files in the Products/mytest directory along with the newtest.cat and newtest.xml files.

PPF file
# # mytest.ppf - automatically generated by PPFCOMPRESS on Mon May 19 14:31:51 2003 # [HEADER] PRODUCT=mytest VERSION=1.1.00 PKGNAME= BOOK=Patrol Knowledge Modules DS_QTEMPL=mytest.xml DESC=mytest Custom Package OSLIST=all RELEASEVER=3.5,7.2 PKG_SIZE=0 PKG_CSIZE=0 INFRASTRUCT_DESIGNATOR= INFRASTRUCT_ROLE= PRODUCT_FAMILY=PATROL [END HEADER] [FILES] ./archives/mytest.ppf;Y;;;644;all ./file_one;Y;;;644;all ./file_two;Y;;;644;all ./file_three;Y;;;644;all

Chapter 6

Using pkgcreate

143

Specifying destination directory and operating system

Specifying destination directory and operating system


This example shows the use of the -o and the -fd arguments.

Command:
pkgcreate -p testd -fs /export/jl/source/ -fd /export/jl/target -o solaris28

Results
If the Index and Products directories do not already exist in the /export/jl/target directory, pkgcreate creates them. Then pkgcreate creates the testd directory as a subdirectory of the Products directory. pkgcreate places a copy of the testd.ppf file in both the Index and the Products/testd directories. pkgcreate places several .gz files in the Products/testd directory along with the testd.cat and testd.xml files. The ppf file contains a line that tells the Distribution Server to only deploy the testd package to Solaris 2.8 computers.

PPF file
# # testd.ppf - automatically generated by PPFCOMPRESS on Mon May 14:45:56 2003 # [HEADER] PRODUCT=testd VERSION=1.1.00 PKGNAME= BOOK=Patrol Knowledge Modules DS_QTEMPL=testd.xml DESC=testd Custom Package OSLIST=solaris28 RELEASEVER=3.5,7.2 PKG_SIZE=0 PKG_CSIZE=0 INFRASTRUCT_DESIGNATOR= INFRASTRUCT_ROLE= PRODUCT_FAMILY=PATROL [END HEADER] [FILES] ./fix.main;Y;;;644;all ./fix.msg;Y;;;644;all ./fix.sh;Y;;;644;all ./archives/testd.ppf;Y;;;644;all 19

144

Distribution Server Getting Started

Importing the package into the Distribution Server

Importing the package into the Distribution Server


A package (or installation image) created by pkgcreate is no different from one created by BMC Software. For this reason, use the typical import process for a pkgcreate package: see Importing components into the repository on page 90 or component import ppf_name [-nowait] on page 116.

Chapter 6

Using pkgcreate

145

Importing the package into the Distribution Server

146

Distribution Server Getting Started

Appendix

Troubleshooting Distribution Server


This appendix contains information for troubleshooting the Distribution Server. This appendix discusses the following topics: Installation problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 The progress indicator remains at 99% . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 The Distribution Client is not imported. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 Uninstallation problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 The InstallEngine subdirectory is not uninstalled . . . . . . . . . . . . . . . . . . . . . . . . . 148 Distribution Client problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 The Distribution Client and Distribution Server cannot communicate . . . . . . . 149 A local installation of the Distribution Client failed . . . . . . . . . . . . . . . . . . . . . . . 150 A deployment (or remote installation) of the Distribution Client failed . . . . . . 152 The Distribution Client has a problem with a required account . . . . . . . . . . . . . 153 The Distribution Client failed to register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 The Distribution Client failed to run due to a system lock-down . . . . . . . . . . . . 155 Common usage problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 The Distribution Manager web page is not available (Error 404) . . . . . . . . . . . . 155 The Distribution Manager web page is not available (Error 503) . . . . . . . . . . . . 156 I cannot log on using some accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 I am prompted for an additional CD when importing components . . . . . . . . . . 157 A configuration question does not apply to my systems . . . . . . . . . . . . . . . . . . . 157 UNIX user authentication problems with the Distribution Server . . . . . . . . . . . 157 Distribution fails on RedHat and SUSE platforms if the CORRECT environment variable is set to cmd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 Security related problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 Gathering troubleshooting information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 Installation files for the Distribution Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 Installation logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 Distribution Server logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 Web server logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 Distribution Client logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

Appendix A

Troubleshooting Distribution Server

147

Installation problems

Installation problems
This section contains troubleshooting information for the following installation problems.
Problem Type The progress indicator remains at 99% The Distribution Client is not imported Page page 148 page 148

The progress indicator remains at 99%


Problem: The installation is waiting for post-installation scripts, which import the Distribution Client into the Distribution Server, to finish running. The installation status page shows the message, Starting import of DSC. Wait 5 to 10 minutes for the post-installation scripts to run.

Solution:

The Distribution Client is not imported


Problem: You are installing the Distribution Server from a remote drive that the Distribution Server account cannot access. Manually import the Distribution Client.

Solution:

Uninstallation problems
This section contains troubleshooting information for the following installation problem.

The InstallEngine subdirectory is not uninstalled


Problem: After locally uninstalling the Distribution Client, the InstallEngine subdirectory remains in the $BMC_ROOT directory. Manually remove the InstallEngine subdirectory. This will not affect other BMC products installed on the computer.

Solution:

148

Distribution Server Getting Started

Distribution Client problems

Distribution Client problems


This section contains troubleshooting information for the following Distribution Client problems.
Problem Type The Distribution Client and Distribution Server cannot communicate A local installation of the Distribution Client failed A deployment (or remote installation) of the Distribution Client failed The Distribution Client has a problem with a required account The Distribution Client failed to register The Distribution Client failed to run due to a system lock-down Page page 149 page 150 page 152 page 152 page 154 page 155

The Distribution Client and Distribution Server cannot communicate


Problem: The Distribution Server cannot contact the Distribution Client on the network, or the client cannot contact the server. Ensure that you can ping the Distribution Client from the Distribution Server, or ping the server from the client.

Solution:

NOTE
If your environment does not permit the ping command, use the nslookup command instead.

Problem: Solution:

A firewall blocks communication between client and server. See Firewall configuration information on page 82 for information about opening the firewall.

Appendix A

Troubleshooting Distribution Server

149

A local installation of the Distribution Client failed

Problem: Solution:

The Distribution Client uses the wrong URL to contact the Distribution Server. To fix this issue, you have to correct the URL that the Distribution Client uses to contact the Distribution Server and correct the URL that the server sends to the clients. On the Distribution Client system, correct the URL in the BMC_DS_TSERVER_URL parameter of the dsclient.ini file. You can use the procedure in To switch a Distribution Client to a new Distribution Server: local configuration on page 70. On the Distribution Server, use a text editor to correct the URL in the bmc_ds_webserver_url parameter of the ds_config.mof file ($BMC_ROOT\patrol7\lib\mof directory). Restart the Distribution Server after you change this value.

Problem:

A Distribution Client cannot resolve the system name of the Distribution Server from an IP address, or the server cannot resolve the system name of the client. Use a text editor to view the host file on both the Distribution Client and Distribution Server. If needed, correct the value of the IP address or host name for the client or server systems. You can also use the nslookup command to troubleshoot this problem.

Solution:

Problem:

The Distribution Server uses the wrong system name or IP address for the Distribution Client system. In the Distribution Manager, verify that the DNS Name field has the correct system name or IP address for the Distribution Client system. You can find DNS Name on the Properties tab of the Systems page.

Solution:

A local installation of the Distribution Client failed


Problem: Solution: The target system does not have enough hard drive space. Perform the following steps: 1. Ensure that the target system has enough hard drive space in the installation and working directories specified in the profile. 2. Remove the system from the Distribution Server.

150

Distribution Server Getting Started

A local installation of the Distribution Client failed

3. Re-add the system to the Distribution Server. 4. Install the Distribution Client again.

Problem:

The installation and working directories in the profile for the system are not valid. For example, on Windows, the specified drives might not exist. Perform the following steps: 1. Ensure that the directories in the profile are valid for that system. The directories do not have to exist. 2. Remove the system from the Distribution Server. 3. Re-add the system to the Distribution Server. 4. Install the Distribution Client again.

Solution:

Problem: Solution:

The Distribution Client is not running. Start the client. See Starting and stopping the Distribution Client on page 66.

Problem:

The installation utility did not copy the files of the Distribution Client to the target system. To verify whether these files were properly installed, see Installation files for the Distribution Client on page 160. If any files are missing, re-install the Distribution Client.

Solution:

Appendix A

Troubleshooting Distribution Server

151

A deployment (or remote installation) of the Distribution Client failed

A deployment (or remote installation) of the Distribution Client failed


Problem: Solution: The installation method failed during the deployment. If the Distribution Server and target system are Windows platforms, verify that the Remote Registry Service and Task Scheduler are running on the target and that the Administrative share (i.e., C$, D$, etc.) is enabled on the target system. Otherwise, verify that at least one of the following installation methods is running on the target:
s s s

SFTP and SSH FTP and Telnet PATROL Agent 3.5.30 or later

For more information about installation methods, see Appendix B, Requirements for distributing the Distribution Client from the Distribution Server.

Problem:

A deployment of the Distribution Client failed between a Distribution Server and target system that are both on Windows platforms. Before trying the deployment again, map a network drive (i.e. C$) from the Distribution Server system to the target system. Use a privileged account to map this network drive. Ensure that the Administrative share (i.e. C$, D$, etc.) is enabled on the target system.

Solution:

Problem: Solution:

A deployment of the Distribution Client failed for unknown reasons. Research the failure by reading the log files on the Distribution Server that relate to deploying clients. These log files exist in the following directories:
s s

$BMC_ROOT/Patrol7/log/ds/PI/ (UNIX) %BMC_ROOT%\Patrol7\log\ds\PI\ (Windows)

In these directories, look for file names that display the host name of the target system. Also read the pitool.log file because it contains information about the status of client deployments.

152

Distribution Server Getting Started

The Distribution Client has a problem with a required account

The Distribution Client has a problem with a required account


Problem: The connection account or privileged account does not exist on the target (or Distribution Client) system. Or these accounts do not meet the requirements. For the account requirements, see About the connection account and Distribution Client account on page 94 and About the privileged account on page 96. Correct these problems by performing the following steps: 1. 2. 3. 4. 5. Create the accounts on the target system (if needed). Ensure that the accounts meet the requirements. Remove the system from the Distribution Manager. Add the system to the Distribution Manager. Install the Distribution Client again.

Solution:

NOTE
To remove or add a system to the Distribution Manager, see the Distribution Manager Help.

Problem:

The Distribution Client is locked out because someone changed the password for a required account in the operating system, but did not also change the password in the Distribution Client. If the connection or privileged account is the problem, change the password in the Distribution Manager by using the Account list on the Systems tab. For more information, see the Distribution Manager Help. If the Distribution Client account is the problem, see Updating the Distribution Client account on page 78. If the Distribution Client Default or Registration account is the problem, see Updating the Distribution Client default and registration accounts on page 76.

Solution:

Appendix A

Troubleshooting Distribution Server

153

The Distribution Client failed to register

The Distribution Client failed to register


Problem: Solution: Registration failed for the Distribution Client and you want to try registration again. To re-register the Distribution Client, follow these steps: 1. Remove the Distribution Client system from the Distribution Manager, and add it again. For more information, see the Distribution Manager Help. 2. Stop the Distribution Client, as described in Starting and stopping the Distribution Client on page 66. 3. On the Distribution Client system, delete the dshostid.conf file from the following directory.
s s

%BMC_ROOT%\dsclient\config (Windows) $BMC_ROOT/dsclient/config (UNIX)

4. Restart the Distribution Client. 5. In the Distribution Manager, run the System Registration report, and register the Distribution Client system if it appears on this report.

Problem: Solution:

The Distribution Manager cannot automatically register the Distribution Client. In the Distribution Manager, change the Global Options to allow automatic registration. Or run the System Registration report in the Distribution Manager and manually register the Distribution Client. For more information, see the Distribution Manager help.

Problem:

The Distribution Client failed to register because the Distribution Server, RTserver, or web server was not running. Ensure that the Distribution Server, RTserver, and web server are running; and then restart the Distribution Client, as described in Starting and stopping the Distribution Client on page 66.

Solution:

NOTE
You have to manually register if auto-registration is disabled in the Distribution Manager.

154

Distribution Server Getting Started

The Distribution Client failed to run due to a system lock-down

The Distribution Client failed to run due to a system lock-down


Problem: A network or system administrator has restricted access to the Distribution Client system so that users cannot install or run the Distribution Client. Contact the administrator for help.

Solution:

Common usage problems


This section contains troubleshooting information for the following problems.
Problem Type The Distribution Manager web page is not available (Error 404) The Distribution Manager web page is not available (Error 503) I cannot log on using some accounts I am prompted for an additional CD when importing components A configuration question does not apply to my systems UNIX user authentication problems with the Distribution Server Distribution fails on RedHat and SUSE platforms if the CORRECT environment variable is set to cmd Page 155 156 156 157 157 157 158

The Distribution Manager web page is not available (Error 404)


Problem: Solution: The URL is incorrect. Type the correct URL. Be sure to check the following:
s s s s

protocol (http vs. https) Web server name port number for the web server (if not 80 or 443) case (if the web server is on a UNIX system)

Problem: Solution:

The web server is not running. Start the web server.


Appendix A Troubleshooting Distribution Server 155

The Distribution Manager web page is not available (Error 503)

The Distribution Manager web page is not available (Error 503)


Problem: Solution: The RTserver or Distribution Server is not running. Start the RTserver, Distribution Server, and web server, in that order. For more information, see Starting and stopping programs on page 61.

Problem: Solution:

The Distribution Server might not be using the correct RTserver. Ensure that the the Distribution Server is using the correct RTserver. For more information, see Changing the RTserver on page 71.

I cannot log on using some accounts


Problem: The account does not belong to the appropriate groups on the Distribution Server system. Ask your system administrator to add the account to the appropriate group or groups.

Solution:

Problem:

The account is a domain account, but you did not preface the account with the domain name. Preface the account name with the domain name.

Solution:

Problem:

The account is a domain account, but the Distribution Server is not configured to accept domain accounts. Ask your system administrator to change the Distribution Server account to a domain account. For more information, see Updating the Distribution Server account on page 75.

Solution:

156

Distribution Server Getting Started

I am prompted for an additional CD when importing components

I am prompted for an additional CD when importing components


Problem: The products that you are importing have dependencies on a different CD. For example, the files for a specific platform might be on a different CD. Since the Distribution Server imports all platforms of a product at a time, it requests the additional CDs. If you know that you will not need the files on the other CD, you can skip importing those files.

Solution:

A configuration question does not apply to my systems


Problem: The components in the collection can be installed on multiple platforms, so the configuration asks questions for all possible platforms. Answer the question. When the configuration is associated with a specific system, answers for configuration questions that do not apply are ignored.

Solution:

UNIX user authentication problems with the Distribution Server


Problem: On UNIX platforms, the Distribution Server requires a root setuid program. If this program does not have root privileges, users cannot login or authenticate themselves to the system. Following are ways to avoid user authentication errors for different installation scenarios where this problem may occur.

Solution:

Installing into an NFS client mounted installation directory


When you install the Distribution Server into an installation directory that is an NFS client mount, which means file, directory, and mount permissions are controlled by an NFS server, verify that the root user owns the Distribution Server binary, which is the executable file in the $BMC_ROOT/Patrol7/bin/platform directory. Also, ensure that that the set user id bit is set to mode 6755.

Appendix A

Troubleshooting Distribution Server

157

Distribution fails on RedHat and SUSE platforms if the CORRECT environment variable is set to cmd

NOTE
All root operations may fail during installation because of the permissions controlled by the NFS server on the same exported filesystem.

Installing to an operating system with Extended Security


When you install the Distribution Server to a computer with an operating system with extended security (such as Trusted Solaris), ensure that the Distribution Server account has the privileges, roles, and rights to run a setuid root program in the installation directory.

Installing into a locally mounted installation directory


If you install the Distribution Server into an installation directory that is locally mounted, ensure that the setuid attribute is turned on for the mounted directory.

Distribution fails on RedHat and SUSE platforms if the CORRECT environment variable is set to cmd
Problem: On SUSE platforms, by default, the CORRECT environment variable is cmd. When the CORRECT environment variable in /etc/csh.cshr is set to cmd, the shell tries to correct what it perceives as command line typing errors. This causes the shell command line to attempt to correct the telnet commands for the client installation, causing the protocol to fail. If the connection account for a client computer has the tcsh shell as the default shell and if the telnet protocol of the client installation is to be used to install the client on that computer, then you should ensure that the environment variable CORRECT is not set.

Solution:

NOTE
For RedHat platforms, the CORRECT environment variable is not set by default. This problem only occurs on RedHat if the default value of CORRECT is changed to cmd.

158

Distribution Server Getting Started

Security related problems

Security related problems


See the PATROL Security User Guide for troubleshooting information relating to security. This section also contains additional troubleshooting information for security related problems. Problem: At security level 4, you get one of the following errors when you try to access the Distribution Manager web page.
s s

HTTP Error 403 The page cannot be displayed.

Cause:

The web browser does not have a certificate installed, or the web browser does not support the level of encryption used by the web server. Install the web browser certificate and verify that the web browser supports the level of encryption required by the webweb server. For example, if the web server uses 128 bit encryption, the browser must also use 128 bit encryption.

Solution:

Problem:

Distribution Server does not recognize the PATROL Agent on a system to which you want to install the Distribution Client. Verify that these aspects of PATROL Security are true:
s s s

Solution:

Port number is correct. PATROL Agent and Distribution Server use the same security level. All trial keys and certificates from BMC Software are current.

NOTE
Ignore the preceding bullet if you use your own certificates. See PATROL Security Components Technical Bulletin (May 21, 2003).

Gathering troubleshooting information


This section contains information about locating installation logs, Distribution Server logs, web server logs, and Distribution Client logs.

Appendix A

Troubleshooting Distribution Server

159

Installation files for the Distribution Client

Installation files for the Distribution Client


The table in this section shows the installation files for the Distribution Client. You can verify an installation of the client by finding out whether these files exist in the following directories:
s s

$BMC_ROOT/dsclient/config (UNIX)

%BMC_ROOT%\dsclient\config (Windows)
Client Installation Files on UNIX ds_listener dsclient dshostid.conf dsclient.ini ds_listener.log dsclient.log dsclient_startup.log

Client Installation Files on Windows ds_listener.exe ds_client.exe dshostid.conf dsclient.ini ds_listener.log dsclient.log dsclient_startup.log

Installation logs
One log file is created each time the installation utility is run. The name of the log file is a combination of the computer name and a time stamp. The location of the file depends on the operating system.
s

On Windows, the log file is saved to the Document and Settings\username\Application Data\BMCinstall\ directory. On UNIX, the log file is saved to the home_directory/BMCINSTALL/ directory.

Distribution Server logs


The log files for the Distribution Server are located in subdirectories of the $BMC_ROOT/Patrol7/log/ds directory. The table below describes the types of logs found in each subdirectory.
Subdirectory of $BMC_ROOT/Patrol7/log/ ds ds/component/delete

Type of log files This directory contains the Distribution Server log files. This directory contains the log files on the component delete action.

160

Distribution Server Getting Started

Web server logs

Subdirectory of $BMC_ROOT/Patrol7/log/ ds/component/export ds/component/import ds/config/export ds/deploy ds/manager ds/PI/x

Type of log files This directory contains the Distribution Server component export log files. This directory contains the Distribution Server component import log files. This directory contains the configuration export log files. This directory contains the Distribution Server distribution log files. This directory contains Distribution Manager debug log files. The logs in this folder describe the installation of the Distribution Client, and the status of deployments to that client.

Web server logs


Which web server logs you have depends on the web server used on your operating system. Windows installations of the Distribution Server use the IIS web server. UNIX installations of the Distribution Server use the Apache web server.

IIS web server logs


The IIS web server maintains log files and also places messages in the Windows Event log. The logs for IIS are located in the system_dir\LogFiles\w3svcl\ directory. These logs are most useful for monitoring HTTP requests.

Apache web server logs


The Apache web server maintains the log files in the $BMC_ROOT/common/apache/apache.1.3.33/OS/logs/ directory. The error_log file contains information about port conflicts and startup problems. The Apache web server log files can grow considerably over the course of time. For example, each image load request is logged. The installation installs a utility to truncate the log files for the Apache web server while the web server is running, so that they do not grow without limit.

Appendix A

Troubleshooting Distribution Server

161

Distribution Client logs

The utility consists of the following files:


s s

the /etc/patrol.d/apache/bmctrimlog executable utility the /etc/patrol.d/apache/bmctrimlog.conf text configuration file

This utility can be run periodically as a job in the root crontab. If you chose to automatically add the job to the root crontab in the installation, the following line is added, which runs the utility every hour on the half-hour.
30 * * * * /etc/patrol.d/apache/bmctrimlog

If you chose to not add the job to the root crontab, you can add the job manually and adjust the job schedule. For more information about cron and crontab, see the man pages for them for your system. To fine-tune the log file management, edit the bmctrimlog.conf file. For example, you can set different maximum sizes for each log file. See the comments in the configuration file for more information.

Distribution Client logs


The log files for the Distribution Client are located in the $BMC_ROOT/dsclient/log directory. The following table describes the types of log files that the Distribution Client keeps.
Log file name dslistener.log dsclient_startup.log dsclientx.log Description Describes the startup, process, and shutdown of the listener. Describes the startup of the Distribution Client. Describes the Distribution Client process.

NOTE
When the Distribution Client creates a new log file, it does not overwrite the existing files. Instead it renames the existing files assigning an increasing number to each file. The more recent files have lower numbers than older files. The most recent file does not have a number. For example, dsclient.log is the most recent client log file and dsclient1.log is the next most recent.

162

Distribution Server Getting Started

Appendix

Requirements for distributing the Distribution Client from the Distribution Server
B

This appendix contains information for distributing the Distribution Client from the Distribution Server. This appendix discusses the following topics: About distributing the Distribution Client from the Distribution Server . . . . . . . . . Discovering the platform of the target system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Copying and executing the installation package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Registering the Distribution Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About installation methods for distributing the Distribution Client . . . . . . . . . . . . . Setting and prioritizing installation methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using a PATROL Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reading the registry (Windows only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using a mapped drive and task scheduler service (Windows only) . . . . . . . . . . Using SFTP and SSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using FTP and Telnet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About simultaneous distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About timeouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 164 165 165 166 166 166 167 168 169 171 174 175

Appendix B

Requirements for distributing the Distribution Client from the Distribution Server

163

About distributing the Distribution Client from the Distribution Server

About distributing the Distribution Client from the Distribution Server


Distributing the Distribution Client from the Distribution Server involves the following steps: 1. Discovering the platform of the target system. 2. Copying and executing the installation package. 3. Registering the Distribution Client.

Discovering the platform of the target system


The Distribution Server uses the following methods to discover the platform of the target system: 1. PATROL Agent. The Distribution Server attempts to connect to a PATROL Agent on the target system, copy a discovery script to the system, and execute the script using the PATROL Agent. 2. Reading the registry. If the Distribution Server is a Windows system, it attempts to read the registry of the target system. 3. Mapped Drive and Task Scheduler Service. If the Distribution Server is a Windows system, it attempts to map a drive to the target system, copy a discovery script to the system, and execute the script using the Task Scheduler service. 4. SFTP/SSH. The Distribution Server attempts to copy a discovery script to the system using sftp and execute the script using ssh. 5. FTP/Telnet. The Distribution Server attempts to copy a discovery script to the system using ftp and execute the script using telnet.

NOTE
The Distribution Manager determines which installation methods are tried in which order. For more information about installation methods, see the Distribution Manager Help System.

Once the Distribution Server identifies the platform of the target system, the it verifies that the platform is supported and selects the appropriate installation package from the component repository to install the Distribution Client on that system. If all methods of discovering the platform fail or if the platform is not supported, the Distribution Server cannot install the Distribution Client on the target system.
164 Distribution Server Getting Started

Copying and executing the installation package

Copying and executing the installation package


The second step in distributing the Distribution Client is copying the installation package to the remote system and executing it. The Distribution Server uses the same method for copying and executing the installation package as it used to copy and execute the discovery script. If the Distribution Server discovered the platform information using the remote registry, it uses a mapped drive and the Task Scheduler service to copy and execute the installation package. When the installation is complete, the installation log file is copied back to the server and displayed in the reports. The status of the system is also updated.

Registering the Distribution Client


The final step in distributing the Distribution Client is registering the Distribution Client with the Distribution Server. In order for registration to work, the Distribution Client must be able to contact the Distribution Server using the host name provided by the Distribution Server. When the Distribution Client starts up, it uses http or https (depending on the security level) to notify the Distribution Server that it is up and running. The Distribution Server recognizes the Distribution Client as a system to which it distributed the Distribution Client, and sets the status of the system to initialized. You can now distribute products to the system. Note that if you locally install the Distribution Client, a similar registration process occurs. The Distribution Client notifies the Distribution Server specified in the installation that it is up and running. However, the Distribution Server does not recognize the Distribution Client. You must manually register the system using the System Registration report before the Distribution Server sets the status of the system to initialized.

Appendix B

Requirements for distributing the Distribution Client from the Distribution Server

165

About installation methods for distributing the Distribution Client

About installation methods for distributing the Distribution Client


The Distribution Server uses the following installation methods for discovering the platform of the target system, and copying and executing the installation package: 1. PATROL Agent 2. Reading the registry (Windows only, used only to discover the platform of the target system) 3. Mapped Drive and Task Scheduler service (Windows only) 4. SFTP and SSH 5. FTP and Telnet

Setting and prioritizing installation methods


You can determine which installation methods the Distribution Server uses and in which order the Distribution Server tries these methods. For example, if you do not have a PATROL Agent installed on the target system, disable the agent installation method. If the Distribution Server and Distribution Clients are both Windows systems, configure the Windows installation method to run before other methods. To set installation methods, use the Set Install Methods page of the Distribution Manager or the ds setglobal command of the Distribution Server Command Line Interface. For the Set Install Methods page, see the Distribution Manager Help, and for the ds setglobal command, see Managing preferences on page 131.

Using a PATROL Agent


One method of copying the discovery script and installation package to the target system and executing them is to use an existing PATROL Agent on the target system. For this method to work, the following conditions must be met:
s

A PATROL Agent v3.5.30 or later, depending on the security level, must be running on the target system.

166

Distribution Server Getting Started

Reading the registry (Windows only)

The PATROL security level of the target system and the Distribution Server must be compatible. The PATROL Agent account must have rights to create or access to the working directory and installation directory and copy files to those directories.

When using this method, the Distribution Server does the following: 1. The Distribution Server attempts to discover to a PATROL Agent on the system using the port in the profile for the system. 2. If a PATROL Agent is discovered, the Distribution Server uses the connection account for the system to connect to the PATROL Agent. 3. The Distribution Server uses the PATROL Agent to transfer the discovery script or installation package to the working directory specified in the profile for the system. If the working directory does not exist, the Distribution Server has the PATROL Agent create it. 4. The Distribution Server creates a new OS task on the PATROL Agent to execute the discovery script or installation package.

PATROL Agent and Distribution Server security levels


The security level of the PATROL Agent must match the security level of the Distribution Server. For PATROL Agent versions 3.5.30 and later, the Distribution Server and the PATROL Agent must use the same security level.

Reading the registry (Windows only)


If the Distribution Server is located on a Windows system, the Distribution Server attempts to read the registry of the target system to determine the platform of the target system. For this method of discovering the platform to work, the following conditions must be met:
s

The Distribution Server must be a Windows system. If the target system is a Windows system, the Remote Registry service on the system must be running.

Appendix B

Requirements for distributing the Distribution Client from the Distribution Server

167

Using a mapped drive and task scheduler service (Windows only)

The Distribution Server uses the privileged account to connect to the system and access the remote registry service. If the Distribution Server discovers the platform information using the remote registry, it uses a mapped drive and the Task Scheduler service to copy and execute the installation package.

Using a mapped drive and task scheduler service (Windows only)


If the Distribution Server is a Windows systems, one method of copying the discovery script and installation package to the target system and executing them is to use a mapped drive and the Task Scheduler service. For this method to work, the following conditions must be met:
s

Both the Distribution Server and the target system are Windows systems. The administrative drives (for example, C$, D$) must be shared on the target system. The Task Scheduler service must be available on the target system. If the Task Scheduler service on the system is not started, the Distribution Server will start it. If the Distribution Server is running on a Windows 2003 system, the Distribution Server account and Distribution Client account must have the same name. In addition, the client account must be a member of the Administrators group and have the following user rights:
s s s s s

Act as part of the OS Increase quotas Log on as a batch job Log on as a service Replace a process level token

When using this method, the Distribution Server does the following: 1. The Distribution Server identifies the drive for the working directory in the profile for the system. 2. The Distribution Server maps the drive for the working directory on the target system as a network drive, using the privileged account for the system. 3. If the working directory does not exist, the Distribution Server creates it.

168

Distribution Server Getting Started

Using SFTP and SSH

4. The Distribution Server copies the discovery script or installation package to the working directory. 5. The Distribution Server uses the Task Scheduler service to execute the discovery script or installation package.

Using SFTP and SSH


One method of copying the discovery script and installation package to the target system and executing them is to use SFTP and SSH. For this method to work, the following conditions must be met before installing a Distribution Client:
s

The SFTP and SSH servers must be running on the target system. (The SFTP and SSH servers might be the same.) The SFTP server must support the commands listed under SFTP commands used on page 170. The corresponding SFTP and SSH clients must be on the Distribution Server and in the system path. The SFTP and SSH setup must be configured and verified. All SFTP and SSH client systems must be added to the list of known hosts on the Distribution Server system.

When using this method, the Distribution Server does the following: 1. The Distribution Server runs its SFTP client and connects to the SFTP server on the target system using the connection account for the system. 2. The Distribution Server uses SFTP to copy the discovery script or installation package to the working directory specified in the profile for the system. If the working directory does not exist, the Distribution Server creates it. 3. The Distribution Server runs its SSH client and connects to the SSH server on the target system using the connection account for the system. 4. The Distribution Server uses the SSH client to execute the discovery script or installation package.

Appendix B

Requirements for distributing the Distribution Client from the Distribution Server

169

Using SFTP and SSH

Using SFTP and/or SSH on Microsoft Windows Distribution Servers


When using SFTP and/or SSH on Microsoft Windows Distribution Servers a slave drive program is used to emulate a terminal. The terminal emulation program can communicate with the SFTP and/or SSH with or without pipes. Some combinations of Microsoft Windows and SFTP and/or SSH require the use of pipes; while others require that pipes not be used. By default, when using the SFTP protocol on a Microsoft Windows Distribution Server, pipes are not used. If errors such as "No data for 100 seconds" or "Error in peeknamedpipe" are present in the detailed log file for the Client Installation program (pitool_hostname.log), create an empty file named bUsePipes in the directory BMC_BASE/ds/PI/bin. The presence of this file will cause the Client Installation slave drive program to use pipes.

SFTP commands used


The Distribution Server uses the following SFTP commands. They must be supported by and enabled on the sftp server on the target system.
s s s s s s s s s s s s

cd exit help lcd ls mkdir put pwd quit rename rm version

SFTP and SSH services


BMC Software used the following SFTP and SSH services in the development and testing of the Distribution Server:
Service SFTP/SSH SFTP/SSH Application cygwin (Windows) OpenSSH 3.1 (UNIX)

170

Distribution Server Getting Started

Using FTP and Telnet

Using FTP and Telnet


One method of copying the discovery script and installation package to the target system and executing them is to use FTP and telnet. In order for this method to work, the following conditions must be met:
s

A suitable FTP server and telnet service must be running on the target system. The FTP server must support the commands listed under FTP commands used on page 172. The corresponding FTP and telnet clients must be on the Distribution Server and in the system path.

When using this method, the Distribution Server does the following: 1. The Distribution Server runs its FTP client and connects to the FTP server on the target system using the connection account for the system. 2. The Distribution Server uses FTP to copy the discovery script or installation package to the working directory specified in the profile for the system. If the working directory does not exist, the Distribution Server creates it. 3. The Distribution Server runs its telnet client and connects to the telnet server on the target system using the connection account for the system. 4. The Distribution Server uses telnet to execute the discovery script or installation package.

Appendix B

Requirements for distributing the Distribution Client from the Distribution Server

171

Using FTP and Telnet

FTP commands used


The Distribution Server uses the following ftp commands. They must be supported by and enabled on the ftp server on the target system.
s s s s s s s s s s s

ascii binary cd delete lcd mdelete mkdir mput prompt put user

Requirements for the FTP and Telnet service


By default, Windows systems do not have FTP and telnet services. If the Distribution Server is installed on a UNIX system and distributes the Distribution Client to a Windows system, you must have a suitable ftp and telnet service installed on the target Windows system.
s

The ftp service must be able to connect to any directory, like UNIX, or at least allow reading and writing to the directory that you want to install to. The telnet service must allow connections from a UNIX system. The default telnet service for Windows allows connections from only other Windows systems. If the telnet server uses NTLM authentication, such as the telnet service that comes with Windows 2000, you must disable NTLM authentication for telnet service. The Distribution Server requires standard username and password prompting for authentication. The ftp service must not be configured for restricted access (restricted shell) for the connection account. For example, the WU-ftp defaults to all users running in a restricted shell. The connection account must be able to access or create the working directory for the system using ftp.

172

Distribution Server Getting Started

Using FTP and Telnet

Acceptable FTP and Telnet services


Acceptable FTP and telnet services include the following:
Service FTP Application
s s s s

cygwin (Windows only) IIS FTP (Windows only) WU ftpd (UNIX) Solaris FTP Server (SUNWftpr) cygwin (Windows only) Microsoft telnet service (Windows only) Hummingbird Exceed telnet server (Windows only)

Telnet

s s s

Setting up virtual directories in an IIS FTP server on the target system


If you use the Windows IIS FTP server, you must be able to access the working directory and installation directory specified in the profile for the system. In order to access those directories, you must create the appropriate virtual directories under the default FTP site. If the working directory and installation directory share a common base path, you can create a single virtual directory. The name of the virtual directory must match one of the common parent directories of the working directory and the installation directory. If the working directory and installation directory do not share a common base path, you must create two virtual directories. The name of the virtual directory must match one of the respective parent directories of the working directory or installation directory.

NOTE
When you create a virtual directory, you must also create the corresponding actual directory in the file system.

Example 1: Working directory and installation directory share a common base path
Suppose the working directory and installation directory are as follows:
Directory Installation Directory Working Directory Path C:\Program Files\BMC Software C:\Program Files\BMC Software\DSClient\DScache

Appendix B

Requirements for distributing the Distribution Client from the Distribution Server

173

About simultaneous distributions

Because the working directory and installation directory have a common base path, you can create a single virtual directory. The virtual directory can be any of the following:
Virtual Directory Program Files BMC Software Actual Directory C:\Program Files C:\Program Files\BMC Software

Example 2: Working directory and installation directory do not share a common base path
Suppose the working directory and installation directory are as follows:
Directory Installation Directory Working Directory Path C:\Program Files\BMC Software C:\temp\DScache

Because the working directory and installation directory do not share a common base path, you must create two separate virtual directories: one for the working directory, and another for the installation directory. The virtual directory for the working directory can be any of the following:
Virtual Directory temp DScache Actual Directory C:\temp C:\temp\DScache

The virtual directory for the installation directory can be any of the following:
Virtual Directory Program Files BMC Software Actual Directory C:\Program Files C:\Program Files\BMC Software

About simultaneous distributions


If you distribute the Distribution Client to a system group, the Distribution Server limits the number of systems to which it distributes the Distribution Client at a time in the global options. The limit can be any number from 1 to 10. The default limit is 10.

174

Distribution Server Getting Started

About timeouts

For example, if you distribute the Distribution Client to a system group with more than 10 members, the Distribution Server will distribute the Distribution Client to only 10 systems at a time. If you distribute the Distribution Client to multiple system groups at the same time, the limit applies to each system group. For example, if you distribute the Distribution Client to 3 system groups at the same time, the Distribution Server will effectively distribute the Distribution Client to 30 systems at a time. Keep in mind that maximum number of Distribution Clients that the Distribution Server can distribute at a time is also limited by the memory, CPU, and other resources of the Distribution Server.

About timeouts
When distributing the Distribution Client, the Distribution Server must wait for several operations to complete as part of the process. How long the Distribution Server waits before determining that the operation failed due to a time out is listed in the following table.
Operation Waiting for data to stop arriving from a target system (based on when data starts arriving) Time-out 5 seconds

Waiting for an event to occur, such as waiting for data to arrive from a target 60 seconds system after executing an interactive command Waiting for the completion of a file transfer to a target system Waiting for a discovery or installation script to complete execution on a target system 15 minutes 15 minutes

If you determine that you need to adjust these time-out values, please contact customer support.

Appendix B

Requirements for distributing the Distribution Client from the Distribution Server

175

About timeouts

176

Distribution Server Getting Started

Appendix

Using advanced security


In general, the Distribution Server uses the same security components as PATROL products. This appendix contains information for using the Distribution Server with advanced security levels. For more information about security, including the differences between the levels and how to implement them, see the PATROL Security User Guide. This appendix discusses the following topics: About web communications versus non-web communications . . . . . . . . . . . . . . . . . About security policies and security levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Security policies for the Distribution Server and related components . . . . . . . . About security level mapping for web communications . . . . . . . . . . . . . . . . . . . About the provided certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Certificate signing authorities for the provided certificates . . . . . . . . . . . . . . . . . Expiration dates for the provided certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuration tasks for advanced security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring the web server for security level 1 or 2 . . . . . . . . . . . . . . . . . . . . . . . Configuring the web server and web browser for security level 3 or 4 . . . . . . . Adding the provided trusted root certificate authority to IIS . . . . . . . . . . . . . . . Adding the provided web server certificate to IIS . . . . . . . . . . . . . . . . . . . . . . . . . Requiring client certificates on IIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing the provided certificate to a web browser . . . . . . . . . . . . . . . . . . . . . . . About unattended and attended modes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About replacing the default certificate for the Apache web server . . . . . . . . . . . . . . About unattended and attended modes for the Apache web server. . . . . . . . . . Replacing the default certificate for Apache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About distributing components with advanced security . . . . . . . . . . . . . . . . . . . . . . 178 180 180 181 181 182 182 183 183 183 184 185 186 187 189 189 189 190 191

Appendix C

Using advanced security

177

About web communications versus non-web communications

About web communications versus non-web communications


The Distribution Server and related components use both web communications and non-web communications. The following diagram displays which components communicate to each other using web communications, and which communicate using non-web communication. The type of communications (web versus non-web) influences the following:
s

The default certificates for web versus non-web communications are signed by different certificate signing authorities. For more information, see Certificate signing authorities for the provided certificates on page 182. For non-web communications, both components must have the same security level. However, for web communications, security levels are mapped. For more information, see About security level mapping for web communications on page 181.

Web browser

Distribution Server Command Line Interface

RTserver

Distribution Server

Web server
Web communications

Non-Web communications

Distribution Client

178

Distribution Server Getting Started

About web communications versus non-web communications

The following diagram shows the data flow of the components:

Distribution Client Web browser

PATROL Agent
used only to distribute the Distribution Client

OS Services
used only to distribute the Distribution Client

DMZ DMZ
http / https http / https ping TCP/ UDP/ SSL various

Enterprise managed network Software Distribution web site

Web server (IIS or Apache) pslsp plug-in for Web server Distribution Server

Distribution Server Command Line Interface

TCP/ SSL

Appendix C

Using advanced security

179

About security policies and security levels

About security policies and security levels


The Distribution Server uses the security policies and security levels described in the PATROL Security User Guide. For more information about these security levels, see the PATROL Security User Guide.

Security policies for the Distribution Server and related components


The Distribution Server and related components use policy files as described in the PATROL Security User Guide. For more information about policy files, including their locations and what they include, see the PATROL Security User Guide. The following table lists the policy configuration files or Windows registry entries that correspond to each component.
Component Distribution Server Configuration Files (UNIX) site.plc ds.plc client.plc site.plc pslsp.plc Registry Entries (Windows) site ds site pslsp site dsadmin

Web Server (pslsp plug-in)

Distribution Server Command site.plc Line Interface (and Distribution dsadmin.plc Server when distributing the Distribution Client to a system with a PATROL Agent) Distribution Client site.plc dsclient.plc

site dsclient

In general, components use the security level specified in the site policy. However, the Distribution Client uses the security level in the dsclient policy instead. This allows you to use one security level for distribution, and another security level for other operations. For example, you might want to use a higher security level for distribution than for PATROL Agents, PATROL Console Servers, and PATROL consoles.

180

Distribution Server Getting Started

About security level mapping for web communications

About security level mapping for web communications


The security levels described in the PATROL Security User Guide do not directly apply to web communications. For example, level 1 security uses data encryption but does not use SSL authentication. However, all encrypted web communications, which use https, use SSL authentication. The following table lists how the security levels for the Distribution Server are mapped to communications protocols for web communications and the corresponding security levels for the Distribution Client.
Distribution Server Security Level basic security 1 or 2 3 or 4 Distribution Client Security Level basic security 2 4

Web Communications Protocol http https with server authentication https with mutual authentication

Other combinations of security levels are not supported. For example, the Distribution Client cannot operate at security level 1 or 3.

About the provided certificates


WARNING
This product is delivered with keys and certificates that are not unique to you. BMC Software highly recommends that you promptly change these provided keys and certificates to ones that are unique. If you do not make these changes, there is a higher risk that any third party who gains physical access to your network, or to the data that you send over the internet, might have a better opportunity to use these provided keys and certificates to gain access to your system. BMC Software is not responsible for any damage or liability associated with your use of the provided keys and certificates.

The Distribution Server and its components are delivered with keys and certificates provided by BMC Software. These keys and certificates are supplied only to demonstrate a turnkey security configuration, for purposes such as demos and trial installations. Before using this product, replace the provided keys and certificates with your own unique entities.
s

All components, except for the web server and the web browser, use the certificates specified in their policies. For more information, see Security policies for the Distribution Server and related components on page 180.

Appendix C

Using advanced security

181

Certificate signing authorities for the provided certificates

The certificate provided by BMC Software for the Apache web server is stored in the location specified in the httpd.conf file. For more information, see the SSL documentation included with the Apache documentation at http://hostname:port/manual/mod/mod_ssl, where hostname is the name of the server and port is its http port. For IIS, you must manually install the certificate. For more information, see Adding the provided trusted root certificate authority to IIS on page 184 and Adding the provided web server certificate to IIS on page 185. For the web browser, you must manually install the certificate. For more information, see Installing the provided certificate to a web browser on page 187.

For information about certificates that you must manually configure, see Configuration tasks for advanced security on page 183.

Certificate signing authorities for the provided certificates


The provided certificates used for non-web communications are signed by the WWWQA Testing Certificate Authority, which is describe in the PATROL Security User Guide. The provided certificates used for web communications are signed by the BMC Apache Certificate Authority.

Expiration dates for the provided certificates


The provided keys and certificates used for non-web communications are listed in the PATROL Security User Guide. The provided keys and certificates for web communications are listed below.
Certificate dsclient BMC Apache Certificate Authority (CA) BMC Distribution Client Certificate Expiration Date Valid Begin: Wed Jul 31 19:35:35 2002 Valid End: Sat Jul 13 19:35:35 2013 Valid Begin: Wed May 29 15:18:01 2002 Valid End: Mon Jan 18 14:18:01 2027 Valid Begin: Wed, May 29, 2002 3:25:53 PM Valid End: Sat, May 11, 2013 3:25:53 PM

The dsclient certificate is located in the $BMC_ROOT/common/security/keys/dsclient.kdb file.

182

Distribution Server Getting Started

Configuration tasks for advanced security

Configuration tasks for advanced security


Depending on the security level and the web server, you might have to manually perform some configuration tasks for web communications.

Configuring the web server for security level 1 or 2


When the Distribution Server uses security level 1 or 2, web communications must use HTTPS and the web server must authenticate to the Distribution Client and web browsers with a certificate. For more information, see About security level mapping for web communications on page 181. If you install the Distribution Server on a Windows computer, you must perform the following manual configuration tasks: 1. Add the trusted root certificate authority (see page 184). 2. Add the web server certificate (see page 185). If you install the Distribution Server on a UNIX computer, the Apache web server is automatically configured according to the security level selected at installation.

Configuring the web server and web browser for security level 3 or 4
When the Distribution Server uses security level 3 or 4, web communications must use https and the web server and the Distribution Client and web browsers must mutually authenticate to each other with certificates. For more information, see About security level mapping for web communications on page 181. You must manually install the web browser certificate to each web browser that is used to access Distribution Manager. If you install the Distribution Server on a Windows computer, you must also perform the following manual configuration tasks: 1. Add the trusted root certificate authority (For more information, see page 184). 2. Add the web server certificate (For more information, see page 185). 3. Require client certificates (For more information, see page 186). If you install the Distribution Server on a UNIX computer, the Apache web server is automatically configured according to the security level selected at installation.

Appendix C

Using advanced security

183

Adding the provided trusted root certificate authority to IIS

Adding the provided trusted root certificate authority to IIS


This task describes how to add the provided trusted root certificate authority to IIS. Adding a trusted root certificate authority to IIS is required for advanced security.

Before you begin


The Distribution Server is installed on a Windows computer with IIS.

To add the provided trusted root certificate authority 1 In Windows Explorer, double-click the BMC_demo_ca.crt file in the
%BMC_ROOT%\Patrol7\security directory.

2 Click Install Certificate. 3 On the Certificate Wizard's Welcome screen, click Next. 4 On the Certificate Store screen, click the radio button for Place all Certificates in the
following store.

5 Click Browse. 6 In the Select Certificate Store dialog, check the box next to Show Physical Stores. 7 Expand the tree for Trusted Root Certification Authorities. 8 Highlight Local Computer, and click OK. 9 Click Next to advance to the next wizard screen. 10 Click Finish.
A confirmation appears stating The import was successful.

11 Click OK to close the Certificate window. 12 If you want to verify the import, double click the file BMC_demo_ca.crt.
The Certification Path tab in the Certificate window displays the message The certificate is OK.

184

Distribution Server Getting Started

Adding the provided web server certificate to IIS

Adding the provided web server certificate to IIS


This task describes how to add the provided web server certificate to IIS. Adding a web server certificate to IIS is required for advanced security.

Before you begin


The Distribution Server is installed on a Windows computer with IIS, and you have already added the trusted root certificate authority.

To add the provided web server certificate (Windows 2000) 1 Open the Internet Services Manager using the Start => Programs => Administrative
Tools => Internet Services Manager menu or entering the following at the command

line or the Run dialog: %SystemRoot%\System32\Inetsrv\iis.msc

2 Expand the host in the selection tree and locate the web site from which you will
install the certificate. Example: Default Web Site

3 To display the Web Site Properties dialog box, right-click the web site and choose
Properties.

4 On the Directory Security tab, click Server Certificate. 5 On the Welcome screen for the Web Server Certificate Wizard, click Next. 6 On the Server Certificate window, select Import a Certificate from a Key Manager
backup file and click Next.

7 Type the path or use the Browse button to select the IIS.key file located in the
%BMC_ROOT%\Patrol7\security directory, then click Next.

8 Enter the password bmc then click Next. NOTE


If the password bmc does not work, the certificate has already been imported. In this scenario, go to step 6 and select Assign an existing certificate instead of Import a Certificate from a Key Manager backup file. Click Next and select the appropriate certificate and continue to step 12.

9 On the Imported Certificate Summary window, click Next. 10 On the final screen, click Finish.

Appendix C

Using advanced security

185

Requiring client certificates on IIS

11 If the Web Site Properties dialog box is not open, repeat step 1 through step 3. 12 On the Web Site tab, enter a port number for SSL Port. A typical port number for
SSL is 443.

13 Click OK to close the Web Site Properties dialog box and apply the changes.

Requiring client certificates on IIS


This task describes how to configuring IIS to require a browser certificate. This task is required for security levels 3 and 4.

To require client certificates on IIS 1 Open the Internet Service Manager using one of the following methods:
s

On Windows: choose Start => Programs => Administrative Tools => Internet
Service Manager.

Type the following command using the command line or Run dialog: %SystemRoot%\System32\inetsrv\iis.msc

2 Use the tree view to find the web sites and/or Virtual Directories that need to have
a client certificate requirement. Complete the following steps for each web site or Virtual Directory:

3 Display the Properties sheet by right-clicking the web site or Virtual Directory and
selecting Properties.

4 On the Directory Security tab, in the section labeled Secure Communications (the
yellow key icon), click Edit.

5 In the Secure Communications dialog, select the check box for Require secure
channel (SSL).

6 If you want to use 128-bit encryption, select the check box next to Require 128-bit
encryption in the dialog box.

NOTE
The browser must use the same level of encryption as the web server. For example, if the web server uses 128 bit encryption, the browser must also use 128 bit encryption.

186

Distribution Server Getting Started

Installing the provided certificate to a web browser

7 In the Client Certificate Authentication section, select the radio button for
Require client certificates.

8 Click OK to return to the Properties sheet. 9 Click OK to close the Properties sheet. You may be prompted for whether you
want to override security settings for subdirectories within this web site or Virtual Directory.

Installing the provided certificate to a web browser


For security levels 3 and 4, you must manually install a certificate to the web browser used to access Distribution Manager.

To install the provided web browser certificate on Internet Explorer 1 Copy the BMC_demo_client.pfx from the %BMC_ROOT%\Patrol7\security directory
on the Distribution Server to any location on the target computer.

2 Double-click the BMC_demo_client.pfx file on the target computer. 3 On the Welcome screen of the Import Certificate Wizard, click Next. 4 On the File to Import page, the path to file you selected appears in the File name
field. Click Next.

5 On the Password page, leave the password field empty and click Next. 6 On the Certificate Store page, accept the default selection of Automatically select the
certificate store based on the type of certificate.

NOTE
If the trusted root certificate is already installed, select Place all certificates in the following store. Click Browse, select the Personal folder, then click OK.

7 Click Next and then Finish. 8 A confirmation appears stating The import was successful. 9 Click OK. 10 Open the browser and enter the URL to the web site or Virtual Directory where
you added a client certificate requirement.

Appendix C

Using advanced security

187

Installing the provided certificate to a web browser

To see the Client Certificate prompt, you should use the fully qualified host and domain name (for example myhost.bmc.com) so that Internet Explorer will be in the Internet zone. If you use the host name without the domain, Internet Explorer will be in the Local intranet zone, where the browser may use the client certificate without prompting you. It will still function properly, but it will not be obvious that the client certificate is being used. If you are using the fully qualified domain name, the Client Authentication dialog box appears, which allows you to select a client certificate to use for this host.

11 Select BMC Distribution Client Certificate and click OK.


The web server now allows your request to be processed. The browser will continue to use this Client Certificate for this web host for the duration of the session. To see the client certificate prompt again, you must close all Internet Explorer windows and start the browser again.

To install the provided web browser certificate on Netscape 4.x 1 Copy the BMC_demo_client.pfx from the %BMC_ROOT%\Patrol7\security directory
on the Distribution Server to any location on the target computer.

2 From the Netscape menu, choose Communicator => Tools => Security Info. 3 On the menu on the left, click Certificates, then click Yours. 4 Click Import a Certificate. 5 Select the BMC_demo_client.pfx file and click Open. 6 Click OK on the password windows.
A confirmation appears stating Your certificates have been successfully imported.

7 Click OK. 8 On the menu on the left, click Navigator. 9 Clear the check boxes for any warning messages that you do not want to see. 10 In the Certificate to identify you to a web site field, choose Select Automatically or
BMC_CLIENT certificate.

11 Click OK.

188

Distribution Server Getting Started

About unattended and attended modes

About unattended and attended modes


A component operating in attended mode requires password entry to function. A component running in unattended mode can operate without a password entry. For more information about attended and unattended modes, see the PATROL Security User Guide. By default the Distribution Server and all of its components run in unattended mode. In general, you can follow the instructions in the PATROL Security User Guide for switching components to attended mode, with the following exceptions:
s

If you will distribute the Distribution Client from the Distribution Server, do not set the Distribution Server Command Line Interface (dsadmin policy) to attended mode. The Distribution Server Command Line Interface is launched in the background when the Distribution Client is distributed. If you want to set the Apache web server to attended mode, see About unattended and attended modes for the Apache web server on page 189 for more information.

About replacing the default certificate for the Apache web server
The default certificate installed with Apache is not protected with a password. If you replace this certificate with a certificate that is protected with a password and want to run Apache in unattended mode, you can store the encrypted password in the Apache policy file.

About unattended and attended modes for the Apache web server
By default, Apache runs in unattended mode because its private key in its default certificate is not protected with a password. If you replace the default certificate, you might also have to generate a private key and keystore. If the new keystore is protected by a password, you have the option of running Apache in unattended mode or attended mode.

Appendix C

Using advanced security

189

Replacing the default certificate for Apache

Running Apache in unattended mode


If you replace the default certificate and want to continue running Apache in unattended mode, you must manually update the password in the Apache policy file to match the password for the private key. Apache will automatically retrieve the password from the Apache policy file.

Running Apache in attended mode


If you replace the default certificate and want to run Apache in attended mode you must configure Apache for attended mode. In attended mode, an administrator must manually enter the password when starting Apache, and the Apache policy file is not used. To convert Apache to attended mode, use the SSLPassPhraseDialog directive in the httpd.conf file. For more information, see the SSL documentation included with the Apache documentation at http://hostname:port/manual/mod/mod_ssl, where hostname is the name of the server, and port is its HTTP port. Do not use the plc_password utility that is documented in the PATROL Security User Guide to switch Apache to unattended or attended mode. That method does not apply to starting the Apache web server.

NOTE
Apache operates outside the PATROL Security context. The Apache.plc policy file is used only to store and retrieve the password for the private key, if you replace the default certificate. Other information stored in the file is not used. For more information about policy files, see the PATROL Security User Guide.

Replacing the default certificate for Apache


This task describes how to replace the default certificate installed with Apache with a certificate from a certificate authority.

1 Obtain the certificate from a certificate authority. 2 Installing the new certificate.
See your certificate authority for detailed instructions.

3 If you want to run Apache in unattended mode, use the plc_password utility to
update the password for the Apache.plc policy file to the password for the private key for the new certificate.

190

Distribution Server Getting Started

About distributing components with advanced security

NOTE
The plc_password utility is documented in the PATROL Security User Guide.

4 If you want to run Apache in attended mode, convert Apache to attended mode.
For more information, see Running Apache in attended mode on page 190.

5 Restart the Apache web server.

About distributing components with advanced security


In general, all of the products on a system use the security level specified in the site policy. For more information, see the PATROL Security User Guide. If you always use the same security level for all products in your enterprise, there are no special considerations for distributing products from the Distribution Server versus installing them locally. However, you might need to change the security level for a system. For example, you might want to switch a test environment from a lower security level to a higher security level. In general, all of the products on a system use the security level specified in the site policy, which is overwritten each time you install a product. However when using the Distribution Server, you must take into account the following special considerations:
s

When using the Distribution Server to distribute products with a different security level from products on the system, you must schedule the distribution in the force install mode. Otherwise, the site policy will not be updated. The Distribution Client uses the security level set in the dsclient policy. Any products that you install after the Distribution Client will not affect the security level of the Distribution Client.

Appendix C

Using advanced security

191

About distributing components with advanced security

192

Distribution Server Getting Started

Appendix

D
194 194 195 196 196 196 197 197 198 198 198 199 199 199 200 200 200 201 201 201

Distribution failure messages


Use this appendix to identify and troubleshoot distribution failure messages. This appendix discusses the following topics: Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . List of distribution failure messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Distribution did not happen, system not ready . . . . . . . . . . . . . . . . . . . . . . . . . . . Distribution did not happen - incomplete host data . . . . . . . . . . . . . . . . . . . . . . . Distribution on system failed - multiple versions on some components . . . . . . Distribution on system failed - cache size too small . . . . . . . . . . . . . . . . . . . . . . . Distribution on system did not happen - configuration locales do not match. . Distribution on system did not happen - configuration error detected . . . . . . . Distribution on system did not happen - ds client not found. . . . . . . . . . . . . . . . Distribution on system did not happen - not enough free disk space. . . . . . . . . Wake-up call to client failed. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Timed out during distribution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Timed out during installation phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The installation completed but without components to update in inventory . . Done-failed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The distribution failed due to error on root account . . . . . . . . . . . . . . . . . . . . . . . The installation did not happen due to cache check failure . . . . . . . . . . . . . . . . . The installation completed but failed on post installation action . . . . . . . . . . . . The installation completed with interim errors . . . . . . . . . . . . . . . . . . . . . . . . . . . Distribution on system did not happen - Nothing to deploy (message is displayed on Distribution Status Report) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Appendix D

Distribution failure messages

193

Overview

Overview
The Distribution Server maintains a distribution status for each computer that hosts a Distribution Client. Ideally the distribution status message for each computer should be The DS client is ready for distribution or Done-OK. The first message indicates that the Distribution Client is ready, and the second says that a distribution completed successfully. If the message is anything else, consider it a distribution failure message. Use this appendix to identify and troubleshoot distribution failure messages.

List of distribution failure messages


Distribution failure messages appear in the Distribution Status report and in the installation log files. You can view the Distribution Status report using the Distribution Manager (DM) or the Distribution Server Command Line Interface (CLI). Often the wording of distribution failure messages differs slightly in these interfaces. Use the table in this section to identify distribution messages. The page number column tells you where to find troubleshooting information for each message.
Distribution Manager (DM) Message

Log File Message

CLI Message

Page 195 196

Distribution did not happen, Distribution did not happen - No Deployment Executed system not ready system not ready Uninitialized System Distribution did not happen - Distribution did not happen - No Deployment Executed incomplete host data incomplete host data Incomplete System Data

Distribution on system failed Distribution did not happen - No Deployment Executed 196 - multiple versions on some multiple versions on some Multiple Versions of a Component components components Distribution on system failed Distribution did not happen - No Deployment Executed - cache size too small cache size too small Insufficient Cache Space Distribution on system did not happen - Configuration locales do not match Distribution on system did not happen - Configuration error detected Distribution on system did not happen - DS Client not found Distribution did not happen - No Deployment Executed configuration locale Configuration locale does not mismatch match system locale Distribution did not happen - No Deployment Executed - Errors error in configuration were found in the configuration Distribution did not happen - No Deployment Executed - DS missing dsclient client not found in host inventory No Deployment Executed Insufficient Free Disk Space 196 197

197

198

Distribution on system did Distribution failed - not not happen - not enough free enough free disk space disk space

198

194

Distribution Server Getting Started

Distribution did not happen, system not ready

Distribution Manager (DM) Message

Log File Message

CLI Message No Deployment Executed - Client Wake-up Failed Distribution Timed Out Installation Timed Out Installation completed with no components to update in the inventory Failed Deployment Failed - Need valid root account No Deployment - System failed cache check routine Deployment Failed - Post Installation Failure

Page 198 199 199 199

Wake-up call to client failed. Wake-up call to client failed Timed out during distribution Time-out during file distribution

Timed out during installation Timed out in phase install/uninstall phase The installation completed but without components to update in inventory Done-Failed Done but without components to update in inventory Done Failed

200 200 200

The distribution failed due to Done failed - error on root error on root account account The installation did not happen due to cache check failure Failed due to client cache check failure

The installation completed Done failed on post install but failed on post installation action action The installation completed with interim errors

201

Done but with interim errors Installation completed with an interim error in the exception log Distribution on system did not happen - Nothing to deploy ((message is displayed on Distribution Status Report)

201 201

Failed to deploy distribution Distribution on system did set 'dset_name': Can not find not happen - Nothing to deploy (message is displayed items for this deployment on Distribution Status Report)

Distribution did not happen, system not ready


DM Message: Distribution did not happen, system not ready Log Message: Distribution did not happen - system not ready CLI Message: No Deployment Executed - Uninitialized System Solution: Either no Distribution Client is available on the computer or the client is not working. Install a new Distribution Client, as described in Installing the Distribution Client on page 44.

Appendix D

Distribution failure messages

195

Distribution did not happen - incomplete host data

Distribution did not happen - incomplete host data


DM Message: Distribution did not happen - incomplete host data Log Message: Distribution did not happen - incomplete host data CLI Message: No Deployment Executed - Incomplete System Data Solution: The system is missing some required information such as profile, cache directory, or installation directory. From the Systems tab in the Distribution Manager, you can supply the missing information. For more information, see the Distribution Manager Help.

Distribution on system failed - multiple versions on some components


DM Message: Distribution on system failed - multiple versions on some components Log Message: Distribution did not happen - multiple versions on some components CLI Message: No Deployment Executed - Multiple Versions of a Component Solution: A distribution cannot contain more than one version of a component. If the distribution contains more than one collection, consider moving one or more collections (Distributions tab) to another distribution. If the distribution only contains one collection, modify the collection (Collections tab) so that it contains only one version of each component. For more information, see the Distribution Manager Help.

Distribution on system failed - cache size too small


DM Message: Distribution on system failed - cache size too small Log Message: Distribution did not happen - cache size too small CLI Message: No Deployment Executed - Insufficient Cache Space Solution: The amount of space allocated for the DS Working Directory is too small. In the Advanced Properties of the profile, increase the Maximum Cache Size in the Distribution Manager. For more information, see the Distribution Manager Help.

196

Distribution Server Getting Started

Distribution on system did not happen - configuration locales do not match

Distribution on system did not happen - configuration locales do not match


DM Message: Distribution on system did not happen - Configuration locales do not match Log Message: Distribution did not happen - configuration locale mismatch CLI Message: No Deployment Executed - Configuration locale does not match system locale Solution: The distribution failed because the language (or locale) of the configuration is not compatible to the language of the Distribution Client. When you create a configuration, it belongs to the language specified in the User Preferences of the Options tab. Correct the problem by setting the language in the User Preferences to match the Distribution Client and creating a new configuration. For more information, see the Distribution Manager Help.

NOTE
An English language configuration is compatible with any Distribution Client.

Distribution on system did not happen - configuration error detected


DM Message: Distribution on system did not happen - Configuration error detected Log Message: Distribution did not happen - error in configuration CLI Message: No Deployment Executed - Errors were found in the configuration Solution: The distribution failed because one of the configuration questions has an invalid answer. From the Collections tab in the Distribution Manager, correct the problem by editing the configuration. For more information, see the Distribution Manager Help.

Appendix D

Distribution failure messages

197

Distribution on system did not happen - ds client not found

Distribution on system did not happen - ds client not found


DM Message: Distribution on system did not happen - DS Client not found Log Message: Distribution did not happen - missing dsclient CLI Message: No Deployment Executed - DS client not found in host inventory Solution: The Distribution Client does not exist in the system inventory. From the Systems tab in the Distribution Manager, verify that the Distribution Client was successfully installed by viewing the client status. You can also run a Product Discovery to detect that the Distribution Client is on the system.

Distribution on system did not happen - not enough free disk space
DM Message: Distribution on system did not happen - not enough free disk space Log Message: Distribution failed - not enough free disk space CLI Message: No Deployment Executed - Insufficient Free Disk Space Solution: The distribution failed because the computer that hosts the Distribution Client does not have enough free disk space. Delete files from the client computer to create more disk space.

Wake-up call to client failed


DM Message: Wake-up call to client failed Log Message: Wake-up call to client failed CLI Message: No Deployment Executed - Client Wake-up Failed Solution: The Distribution Server could not contact the Distribution Client. Verify that the client system is available, the Distribution Client is running, and whether the Distribution Server can resolve the DNS name for the client. You can also make the Distribution Client check for distributions more often by decreasing the DS Client Restart Interval in the Advanced Properties of the profile. For more information, see the Distribution Manager Help.

198

Distribution Server Getting Started

Timed out during distribution

Timed out during distribution


DM Message: Timed out during distribution Log Message: Time-out during file distribution CLI Message: Distribution Timed Out Solution: The distribution was interrupted, which is usually due to network problems. Verify the network connectivity and restart the distribution. For busy networks, allow more time for distributions by increasing the Connection Time-out value in the Advanced Properties of the profile. For more information, see the Distribution Manager Help.

Timed out during installation phase


DM Message: Timed out during installation phase Log Message: Timed out in install/uninstall phase CLI Message: Installation Timed Out Solution: The installation on the remote computer may have crashed or is taking too long. For long installations, you can increase the Connection Time-out value in the Advanced Properties of the profile in the Distribution Manager. In the case of a system crash, you can call support at BMC Software.

The installation completed but without components to update in inventory


DM Message: The installation completed but without components to update in inventory Log Message: Done but without components to update in inventory CLI Message: Installation completed with no components to update in the inventory Solution: The remote installation did not return a report of the installed files. Usually a network problem is at fault. From the Systems tab in the Distribution Manager, run a Product Discovery on the system to verify that all files were installed correctly. For more information, see the Distribution Manager Help.

Appendix D

Distribution failure messages

199

Done-failed

Done-failed
DM Message: Done-Failed Log Message: Done Failed CLI Message: Failed Solution: An error occurred during installation. View the installation.log file for the system or call support at BMC Software.

The distribution failed due to error on root account


DM Message: The distribution failed due to error on root account Log Message: Done failed - error on root account CLI Message: Deployment Failed - Need valid root account Solution: An incorrect user name/password was used for the privileged account. From the Systems tab in the Distribution Manager, reenter the user name and password. Also use other protocols such as telnet to verify the user name and password on the target computer. For more information, see the Distribution Manager Help.

The installation did not happen due to cache check failure


DM Message: The installation did not happen due to cache check failure Log Message: Failed due to client cache check failure CLI Message: No Deployment - System failed cache check routine Solution: The distribution never started because the Distribution Server could not find all of the files on the client system that are required for the distribution. Read the installation.log file on the client system to find a more detailed error message, which should be at the top of the log file. Call support at BMC Software if you do not find the log file helpful.

200

Distribution Server Getting Started

The installation completed but failed on post installation action

The installation completed but failed on post installation action


DM Message: The installation completed but failed on post installation action Log Message: Done failed on post install action CLI Message: Deployment Failed - Post Installation Failure Solution: Open the installation.log file on the client system and search on the word "ERROR" to find post installation errors. Call support at BMC Software if you do not find the log file helpful.

The installation completed with interim errors


DM Message: The installation completed with interim errors Log Message: Done but with interim errors CLI Message: Installation completed with an interim error in the exception log Solution: The installation completed successfully even though it encountered some errors. Open the installation.log file on the client system and search on the word "ERROR" to find post installation errors. Call support at BMC Software if you do not find the log file helpful.

Distribution on system did not happen - Nothing to deploy (message is displayed on Distribution Status Report)
DM Message: Distribution on system did not happen - Nothing to deploy (message is displayed on Distribution Status Report) Log Message: Failed to deploy distribution set 'dset_name': Can not find items for this deployment CLI Message: Distribution on system did not happen - Nothing to deploy (message is displayed on Distribution Status Report)

Appendix D

Distribution failure messages

201

Distribution on system did not happen - Nothing to deploy (message is displayed on Distribution Status Report)

Solution: This message is displayed for a variety of reasons. If all the components to be deployed are already installed on the client computer, this message is displayed for an installation deployment. In such instances, the deployment can be forced by using the "force_install" deployment option. This message is also displayed if all components in a distribution are filtered for a particular system because of the infrastructure role or Operating System characteristics.

202

Distribution Server Getting Started

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Index
Symbols
.ppf 141 components about 90 adding to collections 92 custom 140 custom import 140 import 140 importing 90 in collections 91 packaging 140 configurations about 93 creating 93 connection account 94 custom components 140 custom import 140 customer support 3

A
accounts adding in Distribution Manager 98 Apache account 32 connection account 94 Distribution Client account 46, 94 Distribution Client default account 32 Distribution Client registration account 33 Distribution Server account 31 on remote system 94 privileged account 96 root account 31, 47 users on the Distribution Server 61 Apache web server logs 163 trimming log files 35 user name and group 32 Apache.plc (file) 192 attended mode 191

D
directory structure 79 Distribution Client directory structure 81 distributing from the Distribution Server 166 environment variables 82 logs 164 methods of installing 21 port number 48 purpose 15 registration process 167 starting, stopping, and verifying execution 66 Distribution Client account 46, 94 Distribution Client default account 32 Distribution Client registration account 33 Distribution Client working directory 45 distribution failure messages 196 Distribution Manager interface 87 logging off 106 overview 59, 85 purpose 15 where to use 86

B
backing up Distribution Server 68 base installation directories base installation directories 21 in profile 99 BMC Software, contacting 2 BMC_ROOT environment variable 81, 82

C
certificates Apache web server 191 provided 183 signing authorities 184 client security policy 182 collections about 91 creating 92

Index

203

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Distribution Server backing up and restoring 68 components 12 directory structure 80 environment variables 81 features 12 installing 19 logs 162 overview 11 purpose 14 starting, stopping, and verifying execution 63 troubleshooting 151, 157 Distribution Server account 31 Distribution Server CLI about 107 command line arguments 110 commands 112 example scripts 134 modes for running 109 purpose 15 uses 109 Distribution Server web server name 45 distributions about 104 setting up 104 documentation list of documents 16 manuals, availability 16 release notes, availability 16 ds security policy 182 ds_config.sh (file) 31 dsadmin security policy 182 dsclient security policy 182 logs 163 required accounts 29 import custom 140 installable components 28 installation Distribution Client workflow 44 Distribution Server workflow 28 logs 162 troubleshooting 150 installation types default versus custom 26 Internet Guest account for IIS 29 ISAPI extensions for IIS web server 30

L
Launch IIS Process account for IIS 29 logging off 106 logging on to Distribution Manager 87 logs Apache web server 163 Distribution Client 164 Distribution Server 162 IIS web server 163 installation 162

M
manuals, availability 16 mapped drive distributing the Distribution Client 170 installing Distribution Server from 29

E
environment variables 81

N
network requirements 23

F
firewall 82 ftp 173

P
packaging 140 packaging components 140 PATROL Agent 168 PATROL Knowledge Module 140 PATROL Package Format (PPF) 141 PATROL_ROOT environment variable 81 pkgcreate pkgcreate 139 argument descriptions 143 destination directory 144 source directory 144 policy files 182

H
HTTP and HTTPS ports 34, 47

I
IIS ftp server 175 IIS web server about 29 default web site 29 ISAPI extensions 30

204

Distribution Server Getting Started

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
ports Distribution Client port 48 firewall 82 HTTP and HTTPS 47 HTTP and HTTPs 34 RTserver 34 PPFCompress 140 PPFExtract 140 privileged account 96 privileged account,creating with sudo 97 privileges 61 product support 3 products setting up 90 uninstalling with a CD in UNIX environments 56 uninstalling with a CD in Windows environments 56 profiles about 99 creating 99 pslsp security policy 182 sftp 171 site security policy 182 ssh 171 starting Distribution Client 66 Distribution Server 63 RTserver 62 web server 64 stopping Distribution Client 66 Distribution Server 63 RTserver 62 web server 64 sudo, installing and configuring 97 support, customer 3 system groups about 102 creating 103 systems about 100 adding 100 registering 101 setting up 94

R
release notes, availability 16 remote registry 169 reports about 106 running 106 repository repository 140 about 90 root account installing Distribution Client 47 installing Distribution Server 31 root account, using a sudo-privileged account in place of 97 RTserver port 34 purpose 14 starting, stopping, and verifying execution 62 variable setting 33 RTSERVERS environment variable 81

T
task schedule service 170 technical support 3 telnet 173 test urls 65 troubleshooting common usage problems 151, 157 distribution failure messages 196 installation problems 150 security problems 161

U
unattended mode 191 uninstalling products 54 uninstalling products with a CD in UNIX environments 56 in Windows environments 56

S
security configuration tasks 185 distributing components 193 policy files 182 provided certificates 183 security level mapping 183 troubleshooting 161 unattended vs. attended modes 191 using advanced 179 web communications 183

V
virtual directories 175

Index

205

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

W
Web server HTTP and HTTPS port numbers 34 log files 163 purpose 14 starting, stopping, and verifying execution 64 workflow Distribution Client installation 44 Distribution Server installation 28 workflow overview Distribution Manager 89 working directory working directory 45 in profile 99 worksheet Distribution Client installation 48 Distribution Server installation 36

206

Distribution Server Getting Started

Notes

*56056* *56056* *56056* *56056*

*65065*