TIBCO GridServer?? Installation Guide€¦ · TIBCO GridServer® installs into a datasynapse directory within TIBCO_HOME. This directory is referenced in documentation as DS_INSTALL

Two-Second Adv

TIBCO GridServer®

Installation GuideSoftware Release 5.1 SP3August 2013

antage®

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.

USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME.

This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc.

TIBCO, Two-Second Advantage, GridServer, LiveCluster, SpeedLink, and Federator, are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.

Enterprise Java Beans (EJB), Java Platform Enterprise Edition (Java EE), Java 2 Platform Enterprise Edition (J2EE), and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle Corporation in the U.S. and other countries.

All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only.

THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM.

THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.

THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.

This Product is covered by U.S. Patent No. 6,757,730, 7,093,004, 7,093,004, and patents pending.

Copyright © 1999-2013 TIBCO Software Inc. ALL RIGHTS RESERVED.

TIBCO Software Inc. Confidential Information

| v

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xTIBCO GridServer Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xOther Documentation and Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x

Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

Connecting with TIBCO Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvHow to Join TIBCOmmunity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvHow to Access All TIBCO Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvHow to Contact TIBCO Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Chapter 1 introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

GridServer Documentation Roadmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2GridServer Guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Other Documentation and Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Chapter 2 Installation Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5

1) Know the Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2) Meet GridServer System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

3) Optimize GridServer Manager Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8About GridServer Manager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Redundancy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Volume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Component OS and Version Interoperability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Other Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

4) Configure Your Network. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Name Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Director-Broker Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Manager-Engine and Driver-Manager Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Using NAT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Using a VPN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Resource Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Broker-Director Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Direct Data Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17SSL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

TIBCO GridServer® Installation Guide

vi |

5) Install the GridServer Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19GridServer Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19GridServer Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19GridServer Driver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20SpeedLink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Plan Application Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Chapter 3 Manager Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

About Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Installing DataSynapse GridServer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251) Copy files before installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252) Configure server settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253) Start the Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264) Initialize Your Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Changing the Web Administration Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Running Managers From a Different Base Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Running Multiple Managers From a Single Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Installing Into a Read-only Mount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Installing Manager Licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

A Sample Unix rc.d Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Chapter 4 Windows Engine Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Manual Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Manual Installation Notes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Network Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Installing Windows Engines in a Non-Default Location. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Engine Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Configuring Permissions for Processor Utilization Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Configuring Permissions for User Idle Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Engine Configuration and Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Chapter 5 Unix Engine Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Installing the Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Running the Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Read-Only Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Engine Configuration and Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51


| vii

Chapter 6 Driver Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53

GridServer SDK Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54The Java Driver (JDriver) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54The C++ Driver (CPPDriver). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54The Parametric Job Driver (PDriver). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55The .NET Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56COM Driver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Driver Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Configuring Drivers with Multiple Network Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Multiple Driver Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Prohibiting Driver Version Mismatch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Chapter 7 Verify Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59

Submitting a Service Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Monitoring a Service Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Chapter 8 Uninstalling GridServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63

Uninstalling GridServer on Windows Systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Uninstalling an Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Manual Uninstall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Uninstalling a Manager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Uninstalling GridServer on Unix Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Chapter 9 Upgrading GridServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67

Requirements Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Java Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68.NET Framework Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68C++ Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Database Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Other Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

GridServer 5.1 Upgrade Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Prior to Upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71After Stopping the Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71During Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71After Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Engine Upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Driver Upgrade. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Default Engine Configuration Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Default Manager Configuration Changes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77


viii |

Incompatibilities Due to API changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78GridServer 5.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78GridServer 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Mixed-Version Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Mixed-Version Incompatibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Rolling Upgrades. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Prerequisite Actions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Upgrading a Grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Appendix A Database Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Configuring the Reporting Database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Third-Party Database Known Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Microsoft SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Appendix B Kerberos Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Required Knowledge. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Required Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Enabling SSO on the GridServer Administration Tool. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Configuring Windows Active Directory for QSJ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Configuring LDAP in GridServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Installing and Configuring QSJ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Running GridServer as Service Principal User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Configuring Internet Explorer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Verifying a Successful Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Configuring JDriver to use Kerberos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96


| ix

Preface

TIBCO GridServer® is a highly scalable software infrastructure that enables application services to operate in a virtualized fashion, unattached to specific hardware resources. Client applications submit requests to the Grid environment and GridServer dynamically provisions services to respond to the request. Multiple client applications can submit multiple requests in parallel and GridServer dynamically creates multiple service instances to handle requests in parallel on different Grid nodes. This architecture is therefore highly scalable in both speed and throughput. For example, a single client will see scalable performance gains in the processing of multiple requests, and many applications and users will see scalable throughput of the aggregate load.

Topics

• Related Documentation, page x

• Typographical Conventions, page xii

• Connecting with TIBCO Resources, page xv


x |

Related Documentation

This section lists documentation resources you may find useful.

TIBCO GridServer DocumentationThe following documentation is included with GridServer in Adobe Acrobat (PDF) format. To view the guides, log in to the Administration Tool and go to Admin > Documentation. The PDF files are also on the Manager at livecluster/admin/docs. From the Documentation page, you can also search all documentation for a phrase or keywords. The following documents form the GridServer documentation set::

• Introducing GridServer Introduces GridServer and key concepts and terms such as work, Engines, Directors, and Brokers. Read this first if you are new to GridServer.

• GridServer Administration Guide Tells the system administrator how to operate a GridServer installation. It describes scheduling, fault-tolerance, failover, performance and tuning, and other concepts and procedures.

• GridServer Installation Guide Describes how to install GridServer for Windows and Unix, including Managers, Engines, and pre-installation planning.

• GridServer Developer’s Guide Provides information on writing applications for GridServer. Subjects include Service Domains, using Services, PDriver (the Batch-oriented GridServer Client), the theory behind development with the GridServer API, and concepts needed to write and adapt applications.

• GridServer Service-Oriented Integration Tutorial Tutorial on developing applications for GridServer using Services such as Java, .NET, native, or binary executable Services.

• GridServer PDriver Tutorial Tutorial on using PDriver, the Parametric Service Driver, to create and run Services with GridServer.

• GridServer COM Tutorial Tutorial explaining how client applications in Windows can use COMDriver, GridServer’s COM API, to work with services on GridServer.

Other Documentation and HelpAdditional sources of help include:

• GridServer Administration Tool Help Click the context-sensitive help on any page of the GridServer Administration Tool to see online help.


| xi

• API Reference For information on the GridServer API, see the GridServer SDK in the docs directory. Java API information is in JavaDoc format; C++ documentation is in HTML; and .NET API help is in HTMLHelp. You can view and search the API documentation from the GridServer Administration Tool, also: log in to the Administration Tool and go to Admin > Documentation.


xii |

Typographical Conventions

The following typographical conventions are used in this manual.

Table 1 General Typographical Conventions

Convention Use

TIBCO_HOME

DS_INSTALL

DS_MANAGER

DS_DATA

Many TIBCO products must be installed within the same home directory. This directory is referenced in documentation as TIBCO_HOME. The default value of TIBCO_HOME depends on the operating system. For example, on Windows systems, the default value is C:\tibco.

TIBCO GridServer® installs into a datasynapse directory within TIBCO_HOME. This directory is referenced in documentation as DS_INSTALL. The default value of DS_INSTALL depends on the operating system. For example, on Windows systems, the default installation directory is C:\tibco\datasynapse.

The Manager directory contains the read-only software files; by default, it is a directory within DS_INSTALL named manager, and is referred to as DS_MANAGER. For example, on Windows systems, the default Manager directory is C:\tibco\datasynapse\manager.

The data directory is the location of all volatile files used by the application server, such as server properties and configuration. By default, it is a directory within DS_INSTALL named manager-data, and is referred to as DS_DATA. For example on Windows systems, the default data directory is C:\tibco\datasynapse\manager-data

code font Code font identifies commands, code examples, filenames, pathnames, and output displayed in a command window. For example:

Use MyCommand to start the foo process.

bold code

font Bold code font is used in the following ways:

• In procedures, to indicate what a user types. For example: Type admin.

• In large code samples, to indicate the parts of the sample that are of particular interest.

• In command syntax, to indicate the default parameter for a command. For example, if no parameter is specified, MyCommand is enabled: MyCommand [enable | disable]


| xiii

italic font Italic font is used in the following ways:

• To indicate a document title. For example: See TIBCO ActiveMatrix BusinessWorks Concepts.

• To introduce new terms. For example: A portal page may contain several portlets. Portlets are mini-applications that run in a portal.

• To indicate a variable in a command or code syntax that you must replace. For example: MyCommand PathName

Key combinations

Key names separated by a plus sign indicates keys pressed simultaneously. For example: Ctrl+C.

Key names separated by a comma and space indicate keys pressed one after the other. For example: Esc, Ctrl+Q.

The note icon indicates information that is of special interest or importance, for example, an additional action required only in certain circumstances.

The tip icon indicates an idea that could be useful, for example, a way to apply the information provided in the current section to achieve a specific result.

The warning icon indicates the potential for a damaging situation, for example, data loss or corruption if certain steps are taken or not taken.

Table 1 General Typographical Conventions (Continued)

Convention Use

Table 2 Syntax Typographical Conventions

Convention Use

[ ] An optional item in a command or code syntax.

For example:

MyCommand [optional_parameter] required_parameter

| A logical OR that separates multiple items of which only one may be chosen.

For example, you can select only one of the following parameters:

MyCommand param1 | param2 | param3


xiv |

{ } A logical group of items in a command. Other syntax notations may appear within each logical group.

For example, the following command requires two parameters, which can be either the pair param1 and param2, or the pair param3 and param4.

MyCommand {param1 param2} | {param3 param4}

In the next example, the command requires two parameters. The first parameter can be either param1 or param2 and the second can be either param3 or param4:

MyCommand {param1 | param2} {param3 | param4}

In the next example, the command can accept either two or three parameters. The first parameter must be param1. You can optionally include param2 as the second parameter. And the last parameter is either param3 or param4.

MyCommand param1 [param2] {param3 | param4}

Table 2 Syntax Typographical Conventions

Convention Use


| xv

Connecting with TIBCO Resources

How to Join TIBCOmmunityTIBCOmmunity is an online destination for TIBCO customers, partners, and resident experts, a place to share and access the collective experience of the TIBCO community. TIBCOmmunity offers forums, blogs, and access to a variety of resources, including a GridServer-specific community. To register, go to http://www.tibcommunity.com.

How to Access All TIBCO DocumentationAfter you join TIBCOmmunity, you can access the documentation for all supported product versions here:

http://docs.tibco.com/

How to Contact TIBCO SupportFor comments or problems with this manual or the software it addresses, please contact TIBCO Support as follows.

• For an overview of TIBCO Support, and information about getting started with TIBCO Support, visit this site:

http://www.tibco.com/services/support

• If you already have a valid maintenance or support contract, visit this site:

https://support.tibco.com

Entry to this site requires a user name and password. If you do not have a user name, you can request one.


http://www.tibco.com/services/support

https://support.tibco.com

http://docs.tibco.com/

http://www.tibcommunity.com

xvi |


| 1

Chapter 1 introduction

This guide is your starting point for planning, installing, and configuring GridServer for your site. This guide describes how to install, test, and uninstall the Manager, Drivers, and Engines on Windows and Unix platforms.

Use this guide if you are a:

• Business or technology manager planning or assessing requirements for a GridServer installation.

• Engineer or administrator installing and configuring a GridServer system.


2 |

as

o

n

),

g

g e

GridServer Documentation Roadmap

The following documentation is available for GridServer:

GridServer GuidesGridServer provides guides in Adobe Acrobat (PDF) format and print format. To view the guides, log in to the Administration tool and click the Documentation icon. Use the search engine on the Documentation page to search the documentation for a phrase or keywords. You can also see the PDF files on the Manager at livecluster/admin/docs. The following guides are available:

Introducing the GridServer Platform Series:

Introducing GridServer Introduces GridServer and key concepts and terms suchwork, Engines, Directors, and Brokers. Read this first ifyou are new to GridServer.

The DataSynapse GridServer Administration Series:

GridServer Administration Guide Describes how to administer and operate a GridServer installation. It includes information on scheduling, fault-tolerance, failover, and other concepts, plus how-tinformation, and performance and tuning information.

GridServer Installtion Guide Describes how to install GridServer for Windows and Unix, including Managers, Engines, and pre-installatioplanning.

The DataSynapse GridServer Developer Series:

GridServer Developer’s Guide Describes how to develop applications for GridServer, including information on Service Domains, using Services, PDriver (the Batch-oriented GridServer Clientthe theory behind development with the GridServer Tasklet API, and concepts needed to write and adapt applications.

GridServer Object-Oriented Integration Tutorial

Tutorial on developing applications for GridServer usinthe object-oriented Tasklet API in Java or C++.

GridServer Service-Oriented Integration Tutorial

Tutorial on developing applications for GridServer usinServices such as Java, .NET, native, or binary executablServices.


| 3

r)

s ith

Other Documentation and HelpFor additional help, see:

GridServer Administration Tool Help Click the help button on any page of the GridServer Administration Tool to open context-sensitive help.

API Reference GridServer API reference information is in the GridServer SDK in the docs directory. The Java API information is in JavaDoc format, while C++ documentation is in HTML, and .NET API help is in HTMLHelp. You can also view and search API references from the GridServer Administration Tool: log in to the Administration Tool and click the Documentation icon.

Knowledge Base A searchable online archive of known issues and support articles. To access the DataSynapse Knowledge Base, go to the DataSynapse customer extranet site at customer.datasynapse.com and log in. You can also use this site to report an issue, download product updates and licenses, and view documentation.

GridServer PDriver Tutorial Tutorial on using PDriver (the Parametric Service Driveto create and run Services with GridServer.

GridServer COM Tutorial Tutorial explaining how client applications in Windowcan use COMDriver, GridServer’s COM API, to work wservices on GridServer.


4 |

r

lick

ter

Document Conventions

Convention Explanation Example

[bracketed italics] Variable user input Go to http://[hostname], where [hostname] is the computer running youEngine.

bold text Interface labels or options Enter your URL in the Address box and cNext.

Courier New User input, directories, file names, file contents, and program scripts

Run the script in the /opt/datasynapse directory.

[GS Manager Root] The directory where you install GridServer, such as c:\datasynapse or /opt/datasynapse.

The files reside in[GS Manager Root]/webapps/liveclus


| 5

Chapter 2 Installation Overview

This chapter lists prerequisites for a GridServer installation and outlines the installation steps. This chapter assists developers, system architects, and network architects in planning a GridServer production deployment. Read this chapter carefully to prepare for installation.

Before you begin your GridServer installation, determine what GridServer components you must install and how to configure your overall system. You must also prepare for the installation, meet system requirements, and have an overall understanding of GridServer and the installation process.

Topics

• 1) Know the Basics on page 6

• 2) Meet GridServer System Requirements on page 7

• 3) Optimize GridServer Manager Architecture on page 8

• 4) Configure Your Network on page 12

• 5) Install the GridServer Components on page 19


6 |

1) Know the Basics

This guide assumes that you know GridServer concepts. If you do not, see the Introducing GridServer guide for information about the GridServer component architecture and principles of operation. That guide is in your installation package.

You must also be familiar with Windows and Unix operating systems and TCP/IP networking.


| 7

2) Meet GridServer System Requirements

Ensure that your environment meets the minimum hardware and software system requirements for memory, disk space, and processor speed. Please see the DataSynapse Customer Support Web site for the complete list of all hardware and software requirements, including supported operating systems (Windows, Linux, UNIX), Java or .NET software, web browsers, and accompanying components.


8 |

3) Optimize GridServer Manager Architecture

You can deploy the GridServer Manager architecture to give varying degrees of redundancy and load sharing, depending on the available computing resources. To plan an architecture that best supports your needs:

• Determine how your facility wants to use GridServer.

• Estimate expected transaction volume and amount of work.

• Survey hardware and networking requirements for the installation.

About GridServer ManagerA minimal configuration of GridServer consists of a single Manager configured with a Primary Director and a single Broker. You can add additional Managers containing more Brokers or Directors to address redundancy, volume, or other considerations.

You set a Manager’s initial configuration at installation of Manager, on the Manager Type screen. To change the configuration of a running Manager, choose Admin > Manager Reconfigure, follow the screens for Manager reinstallation, and restart the Manager when the configuration is complete.

RedundancyIf you have a minimal configuration including a single Director and single Broker, Engines and Drivers log in to the Director. In this configuration, if the Director fails (as in the case of hardware or network failure), Drivers or Engines cannot establish new connections.

To prevent this problem, run a second Manager with a Secondary Director, and configure Engines and Drivers with the address of both Directors. If the Primary Director fails, Engines and Drivers contact the Secondary Director, which routes Engines and Drivers to Brokers in the same manner as the Primary Director. The


| 9

figure to the left shows an implementation with two Managers.

In addition to redundant Directors, a Broker can have a backup on another Manager. You can designate a Broker to be a Failover Broker on a Manager during installation or in the Manager Configuration page. If no other regular Brokers are available (because of a failure), Directors temporarily route Drivers and Engines to Failover Brokers. The figure to the left shows a Failover Broker on the second Manager.

For more information on redundancy, see the GridServer Administration Guide.

Figure 1 In this typical GridServer installation, there are a primary Director and a secondary Director, installed on two separate systems. On the same system as the primary Director, there is a live Broker. A failover Broker is installed on the same system as the secondary Director. Add Engines and Drivers to the cluster as desired. This configuration is fully redundant but does not do any load sharing.


10 |

VolumeIn larger grids, the volume of Engines in the grid can require more capability than a single Broker can provide. To distribute load, add more Brokers to other Managers at installation. For example, the figure to the right shows a two-Manager system with two Brokers. Directors route Engines and Drivers to Brokers in round-robin fashion.

Component OS and Version InteroperabilityRunning Brokers on the same OS as other components is not a requirement and gives no performance benefit. However, running the same OS for all components does simplify administration and troubleshooting.

A GridServer installation typically requires that GridServer components all reflect the same version. When you upgrade a GridServer Manager, it is best to upgrade all Drivers. However, Drivers are compatible without the added benefits and features of the new version. Engines upgrade themselves automatically. You can run a mixed-version Grid with GridServer 5.0 Brokers with a GridServer 5.1 Director, if you meet certain requirements. See Rolling Upgrades on page 80 for more details

Other ConsiderationsSeveral other factors can influence how you integrate GridServer with your computing environment. These include:

Figure 2 This GridServer configuration shows a Primary Director and a Secondary Director on separate systems and live Brokers on both systems. You can add engines and Drivers to the cluster as desired. This configuration is redundant.


| 11

• Instead of using one grid for all types of Services, you might prefer to divide different subsets of Services (for example, by size or priority) to different Directors.

• Your network can dictate how to plan your Manager environment. For example, if you have offices in two parts of the country and a relatively slow extranet but a fast intranet in each location, you can install a Manager in each location.

• Different Managers can support data used for different Service types. For example, you can configure one Manager for Services accessing a SQL database and another Manager for Services that don’t access the database.

With this flexibility, it’s possible to plan a Manager model to provide a work space that facilitates your workload and traffic. For more information on designing your Manager environment, contact our Integration Services staff, and we can help you determine how to best configure your installation.


12 |

4) Configure Your Network

Since GridServer is a distributed computing application, successful deployment depends on your network configuration. Treat GridServer Managers the same way you treat your other mission-critical file and application servers: assign GridServer Managers static IP addresses and resolvable DNS hostnames. You can configure GridServer Engines and Drivers in several different ways. To receive the full benefit of peer-to-peer communication you must enable communication between Engines and Drivers (the default), but you can also configure GridServer to work with a hub-and-spoke architecture by disabling Direct Data Transfer.

Name ServiceRun GridServer Managers on systems with static IP addresses and resolvable DNS hostnames. In a pure Windows environment, it is possible to run GridServer using just WINS name resolution, but this is not recommended for larger deployments or heterogeneous environments. GridServer does not support DHCP-assigned client addresses for Manager components. DHCP-assigned addresses are acceptable for Engines and Drivers.

Director-Broker CommunicationDirectors and Brokers communicate using TCP on the following ports:

• HTTP communication occurs on port 8000 by default. You can change this to another TCP port at Manager installation or with the Resin Setup option on the Manager Reconfigure page.

• The default Director TCP port that Brokers use for login is 2000, but you can specify another port at installation time or with the Manager Reconfigure page.

• After the Broker logs in, another pair of ephemeral ports is assigned for further communication. You can also configure the Broker and Director to use static ports.

Setting Static Ports for Director-Broker Communication

You can set static TCP ports for communications among Directors and Brokers. To do so, you must install each standalone Director or Broker on a separate machine. For example, to set the communication port between two Directors to 7124, you must install two standalone directors on two machines, and these machines cannot have any Brokers installed or configured. To set the communication port between Brokers and Directors to 7123, you must install each standalone Broker alone on a separate machine.


| 13

Configuration changes are made to all primary and secondary Directors’ director.xml files.

To set the communication port between directors to 7124, edit the primary Director and secondary Directors’ webapps/livecluster/WEB-INF/config/director.xml file and add the port property, as shown below:

<connectionmanager class="ServerSocketConnectionManager" name="Secondary Director Connections"> <property name="address" value="$DSAddress$"/> <property name="permanentConnection" value="true"/> <property name="SSL" value="False"/> <property name="port" value="7124"/></connectionmanager>

Secondary Directors initially log in to the primary or acting primary Director using the port 2000. Then the primary Director notifies secondary Directors to use port 7124 on both sides for further communication.

To set the communication port between Directors and Brokers to 7123, edit the primary Director and secondary Director’s webapps/livecluster/WEB-INF/config/director.xml file and add the add the port property, for example:

<connectionmanager class="ServerSocketConnectionManager" name="Broker Connections"> <property name="address" value="$DSAddress$"/> <property name="SSL" value="False"/> <property name="permanentConnection" value="true"/> <property name="port" value="7123"/></connectionmanager>

Brokers initially log in to the primary or acting primary Director using the port 2000. Then the primary Director notifies Brokers to use port 7123 on both sides for further communication.

You must restart the Directors after making any changes in the director.xml file.


14 |

Manager-Engine and Driver-Manager Communication

All communication between Engines and Managers (Directors and Brokers) and between Drivers and Managers uses the HTTP protocol. The Engine or Driver acts as HTTP client and the Manager acts as HTTP server.

An Engine Daemon periodically checks if its IP address has changed. If so, the Engine Daemon restarts itself and all Engine instances so that they use the new IP address.

Using NATYou can configure the Manager to work with a NAT device between the Manager and the Engines or Drivers. If the untranslated site of the network has no Engines, you can configure to work with a NAT device by specifying the external (translated) address of the NAT device when referring to the Manager address in the Manager URL field during Manager installation, in Driver installation, and in manual Windows, Linux, and Solaris Engine installation.

If clients (Engines and Drivers) exist on both sides of a NAT device, you can configure NAT Translation on the Manager. This enables the URLs used for Manager-to-client communication.

To configure NAT Translation in the GridServer Administration Tool:

1. Choose Admin > Manager Configuration > Communication.

Figure 3 All communication between Engines and Managers or Drivers and Managers is with the HTTP protocol on the port assigned when the Manager is installed. In this diagram we assume the assigned port is 8080. All HTTP communication is initiated by the Engine or Driver as the HTTP client.


| 15

2. Find the NAT Translation heading.

3. The first field, NAT Translation Range, specifies the range of IP addresses within the NAT untranslated network to be translated. In the NAT URL field, type the external URL to use for the Manager on the translated side of the network. If you want the NAT URL used for clients inside the NAT Translation range, set Translate Input Range (True/False) to True; to use NAT translation for clients outside the NAT Range, set this to Outside.

Using a VPNEngines and Clients can run behind a VPN, provided that the Engine Daemon or Driver can determine the correct IP address to use. If VPN client software on the Engine/Client machine handles the VPN, can possibly specify which IP address to use. For Engines, in the Engine Configuration, use the Net Mask setting to force the engine to pick the VPN interface. For Clients, you can set the DSLocalIPAddress property to the IP number of the correct interface.

If an external device like a router handles the Engine/Client-side VPN, it is unlikely that the Engine Daemon or Driver can determine the VPN address. Running Engines or Clients in this configuration is not possible.

Resource SynchronizationNormally, GridServer synchronizes resources from Directors to Brokers, then from Brokers to Engines. However, in situations when you want only to deploy resources to a subset of Engines, you can disable resource synchronization in the Engine Configuration, and then set the lib directory to point to a shared directory containing resources. On the Engine Configuration page, set the Synchronize Resources property in the Resource Validation section to false to disable resource synchronization for that Engine Configuration.

Consider the following business use case: using offsite rented systems (on-demand systems) for Engines. An offsite shared collocation facility hosts some Engine systems. You do not fully trust the collocation provider to erase all sensitive data before reusing the systems, so you keep all resources, including code, on a file server at your site. The offsite Engines have a special offsite Engine Configuration pointing lib directories to a file server at your site. You configure other Engines at your site to use resource deployment in the normal way.


16 |

Broker-Director Communication

Brokers and Directors use TCP to communicate. Communication between Brokers and Directors does not support NAT. By default, the Broker logs in on port 2000 and uses ephemeral ports for further communication. This configuration does not permit a firewall or screening router between the Brokers and Directors.

If you must have a firewall or screening router between Brokers and Directors, ensure the following:

• The firewall or screening router must have the Broker login port (default 2000) open.

• You must configure the Brokers to use static ports for post-login communication, and those ports must be open on the firewall.

This firewall or screening router option is not available by default. Contact our Integration Services staff for help in configuring your system.

Figure 4 All communication between Brokers and Directors is via TCP on the Broker login port (default TCP port 2000)


| 17

Direct Data TransferBy default, GridServer uses Direct Data Transfer, or peer-to-peer communication, to optimize data throughput between Drivers and Engines. Without Direct Data Transfer, all task input and output goes through the Manager. Sending the input and output through the Manager uses more memory and disk on the Manager and results in lower throughput.

Using Direct Data Transfer, the Driver and Engine nodes do the “heavy lifting,” and only lightweight messages go though the Manager. Direct Data Transfer requires each peer to know the IP address that it presents to other peers. In most

cases, therefore, Direct Data Transfer precludes the use of NAT between the peers. Likewise, Direct Data Transfer does not support proxies.

You can install an optional Engine Hook to enable communication between Drivers and Engines when NAT is in use. Contact your DataSynapse Services specialist for information on installing this hook.

For GridServer deployments that use NAT and do not have the optional Engine Hook, you can support NAT between Drivers and Engines by disabling peer-to-peer communication in one of two ways:

Figure 5 When using Direct Data Transfer to move TaskInput data from Drivers to Engines, the Engines “pull” the data via HTTP directly from the Driver. You can configure the Driver's embedded HTTP server to use a static TCP port or an ephemeral TCP port according to the driver.properties file.


18 |

• If, from the perspective of the Drivers, the Engines are behind a NAT device,

the Engines cannot provide peer-to-peer communication. In this case, disable Direct Data Transfer in the Engine configuration.

• If, from the perspective of the Engines, the Drivers are behind an NAT device, then the Drivers cannot provide peer-to-peer communication. Provide the Driver addresses if you know them in advance. Otherwise, disable Direct Data Transfer in the Driver properties file.

SSLDepending on your application server, you can configure your Manager to use SSL selectively or for all component communication and administration.

For information on using SSL, see the GridServer Administration Guide.

Figure 6 When using Direct Data Transfer to move TaskOutput data from Engines to Drivers, the Drivers “pull” the data via HTTP directly from the Engines.


| 19

5) Install the GridServer Components

After preparing for your installation, install the GridServer components. This section introduces the components and directs you to their installation instructions.

GridServer ManagerTo install a Manager, follow the installation procedure in the Manager Installation chapter. You must have a running Manager before you install an Engine.

For more information on installing Managers, see Manager Installation on page 23.

GridServer EngineGridServer Engines come in two variants: Windows Engines and Unix Engines. The following deployment methods are available:

• Manual Installation is supported through a Windows self-extracting installer executable and .tgz files in Unix.

• Windows also supports SMS installation of Engines.

• If you can map a directory on the Broker using Windows file sharing or Samba to be visible to Engines, use Network Installation from Server to run a .bat file when the Engine’s OS is booted. Also, with Unix distributions, you can use an installation script to install Engines remotely.

Security Considerations

On the Windows platform, Engines and Managers run as services owned by the Local System account. To run the Engine with the Local System account, you must reboot after installing the Engine. The Engine then automatically runs as a service after each system reboot.

To prevent unauthorized users from accessing files in the Engine’s directory tree, the Windows system administrator can set up the Engine directory to

• Not inherit permission from the parent directory and

• Grant full access to the built-in SYSTEM and SERVICE users but not grant access to any other users


20 |

On Unix platforms, Engines and Managers install with the file permissions of the user that installs them. That same user must start the Engines and Managers. For this reason, choose a Manager port above 1024.

For directions on installing Engines, see Windows Engine Installation on page 39, and Unix Engine Installation on page 47.

GridServer DriverApplication programs use the GridServer Driver to communicate with the GridServer Manager and thereby leverage the grid’s compute resources. Your application deployment usually bundles the Driver deployment.

SpeedLinkSpeedLink is a high throughput extension to GridServer, and is independently licensed. The GridServer Manager installation places the SpeedLink installer in the [DS Manager Root]/WEB-INF/etc directory. To install SpeedLink, expand SpeedLinkInstall-[version].tar.gz and follow the instructions in the SpeedLink Guide. Note that SpeedLink requires an additional license purchased separately.

DatabaseGridServer uses an included internal database. You can also configure GridServer to use an external reporting database, on an enterprise database system.

For information on database configuration, see Appendix A, Database Configuration, on page 83.

Plan Application DeliveryGridServer supports many options for delivering your software, configuration, and data files to Engines. You can synchronize files between the Manager and the Engines by using Grid Libraries, or the GridServer file replication service. Or, you can configure the Engines to locate key program files such as *.dll, *.so, and *.jar anywhere on the Engine’s file system.

By default, no reporting database is configured. The included HSQLDB reporting database can handle lightweight reporting, but it is primarily for demonstration, development, and integration purposes. For production environments, use an enterprise database system that supports JDBC.


| 21

For information on resource deployment, see the GridServer Administration Guide.


22 |


| 23

Chapter 3 Manager Installation

To begin your DataSynapse GridServer installation, you must install one or more Managers. This chapter describes how to install the Manager and its components such as Primary and Secondary Directors and Primary, Secondary, and Failover Brokers.

This chapter assumes that you are familiar with the previous chapter, Installation Overview on page 5 and know which components you want to install on each Manager.

Topics

• About Installation on page 24

• Installing DataSynapse GridServer on page 25

• Changing the Web Administration Port on page 33

• Installing Manager Licenses on page 36

• A Sample Unix rc.d Script on page 37


24 |

About Installation

The Installation includes an embedded Resin application server, plus the GridServer software, packaged as a tar.gz file, and including the Resin JAR files, Resin bin files, and startup scripts. Use the same archive for Windows, Linux, and Solaris installations. You can download the installation package or get it on a CD-ROM. Make sure the package is available on your machine before you begin.

Other supported platforms are optionally available from DataSynapse customer support as a GridServer update. These typically include a Readme file with further instructions or requirements for installation.


| 25

Installing DataSynapse GridServer

When upgrading from a previous version of GridServer, please see Upgrading GridServer on page 67 and complete all steps before beginning the installation process in this section.

1) Copy files before installationTo copy files used to install GridServer:

1. Decide where to install the Manager. The recommended location for Unix machines is /opt/datasynapse. The recommended location for Windows is c:\datasynapse. This installation procedure refers to this installation directory as [GS Manager Root]. Do not install the Manager in a directory whose name contains a space, such as c:\Program Files. Also, do not install the Manager in a directory that is a symbolic link to another directory.

2. The software ships as a gzipped TAR archive. To unpack it on a Windows system, use WinZip or a similar tool. On a Unix system, use tar and gzip. (Note that with Solaris and HPUX, you must use GNU tar.) For Unix, use the following command:

gzip -d -c GridServer*gz | tar xvf -

3. Make sure that the $JAVA_HOME/jre/lib/ext directory is empty except for the files included with the JRE to avoid classloading issues.

4. Install the unlimited strength JCE for your Java SDK. The files reside in [GS Manager Root]/webapps/livecluster/WEB-INF/etc/jce. Follow the instructions in the README.txt for your SDK to install the files.

2) Configure server settingsIf you need to make changes to any of the following, make the changes to the appropriate config file or environment variable, as required:

Java Settings

You must set the JAVA_HOME environment variable to the root directory of your Java installation.

The TAR file contains the datasynapse directory. If you expand the archive in /opt, you create /opt/datasynapse.


26 |

Windows

To set the JAVA_HOME environment variable:

1. Right click My Computer and select Properties.

2. On the Advanced tab, select Environment Variables, and then add or edit JAVA_HOME to point to where the Java JDK installation is located, for example, C:\Program Files\Java\jdk1.7.0_11.

Unix

To set the JAVA_HOME environment variable, if the Java installation is located in [java-install-dir]:

• Korn and bash shells:

export JAVA_HOME=java-install-direxport PATH=$JAVA_HOME/bin:$PATH

• Bourne shell:

JAVA_HOME=java-install-direxport JAVA_HOME; PATH=$JAVA_HOME/bin:$PATH; export PATH

• C shell:

setenv JAVA_HOME java-install-dirsetenv PATH $JAVA_HOME/bin:$PATHexport PATH=$JAVA_HOME/bin:$PATH

Default File Handle Limit

If you are installing a Manager on a Unix system and plan to run a large grid, you may need to increase the default limit for the number of open file handles. The default on most Unix systems is 1024. In Linux, this is done in the /etc/security/limits.conf file.

3) Start the ManagerStart the Manager according to instructions in the Windows section or Unix section that follows.

Windows

Start the Windows Manager by running the server.bat file, located in the root directory of the GridServer distribution. To test, double-click server.bat to launch the Manager and subsequently start GridServer. This opens a console window containing log messages and a control panel for starting and stopping the Manager.


| 27

You can also run the Manager as a Windows Service. To do so, open a command window and run server.bat with the following arguments:

Unix

Launch the Manager by invoking the server.sh script in the install directory with the start command:

./server.sh start

Subsequently, to stop the Manager, invoke the same script with the stop command:

./server.sh stop

You can also run several Managers using one shared Manager directory. See Running Multiple Managers From a Single Installation on page 34 for instructions.

Other optional arguments that prefix start/stop for the Unix Manager include the following:

You can configure the Manager to launch automatically at system startup and stop cleanly at shutdown. Since the server.sh script conforms to the standard start/stop argument convention (“rc script”), you can accomplish this simply by linking to the appropriate files in the /etc/rc.d directories. For more

Argument Description

[none], run Start the Manager

install

name

Install the Manager as a service, with the name “DataSynapse GridServer Manager name”, where name is optional. If name contains one or more spaces, you must enclose it in quotes.

remove name Remove the Manager’s service named name, where name is optional if you installed without one.

Argument Description

-t Ignore and do not create touchfile.host files. Normally, these files reside in the Manager directory to prevent running multiple Manager instances from the same directory on the same host.

-p Specifies the name and location of the http.pid file used by the Resin application server.


28 |

information on initialization and termination scripts, refer to the init and init.d man pages on your Unix system and see A Sample Unix rc.d Script on page 37.

By default, the server.sh script for Unix systems sets the PATH to /bin:/usr/bin:/usr/local/bin. This can pose an issue if, for instance, the Manager system has perl installed in /opt/perl. To retain the PATH setting that exists in the shell before the Manager is started, set the DS_USE_SYSTEM_PATH to true.

When running a Solaris machine without a graphics card or a Linux machine without X11 libraries and have Java 1.4, edit the last line of server.sh to include the argument -J-Djava.awt.headless=true.

4) Initialize Your ManagerAfter the Manager is running, you must initialize it. Do this one-time process as follows:

3. Start the GridServer Administration Tool

Go to http://<yourhost>:<port>/livecluster to open the installation page.

4. Select Installation Type

Choose a Typical or Custom Manager installation. The default, Typical, installs a primary Director and a Broker with all default settings. If you select Typical, click Next and skip to step 7.

Choose Custom to install a new Manager (for instance to install a secondary Director, failover Broker, or no Broker), upgrade an old installation, or

Figure 7 Selecting Installation Type.


| 29

configure the Resin application server . You must configure Resin before you configure GridServer. If you choose Custom, proceed to step 5.

5. Configure Resin.

You might wish to reconfigure the Resin server to:

— Use an HTTP port other than the default of 8000

— Run multiple Managers on one host using unique HTTP ports

— Set up SSL

— Run with a non-default base directory, such as for running multiple Managers from a single share

To configure Resin, select Resin Configuration from the Manager Configuration page and click Next. Enter values for each of the seven screens.

IMPORTANT: When you reconfigure the Manager to change the Resin port after your initial installation, the port change does not take place in existing Engine configurations. Consequently, Engines cannot log in after the Manager Reconfigure process, and you must re-install them. To avoid this issue, see Reconfiguring the Resin Port in the GridServer Administration Guide.

6. Enter Configuration Values.

In the GridServer Manager Configuration page, select New Manager Installation, click Next, and enter values for each applicable item on each screen. For information on any page, click Page Help.

Figure 8 Selecting installation, upgrade, or Resin configuration.


30 |

The following issues may require different configuration than a typical install:

7. Verify and Install. After you complete a Custom or Typical installation, the Verify Setup

Issue Configuration Information

Upgrades Before installation, move your previous version of GridServer toanother location. On the GridServer Manager Setup page, type the path to your old installation in the Previous Base Directory box. GridServer migrates your old settings to your new installation.

When upgrading from a previous version of GridServer, please see Upgrading GridServer on page 67 and complete all steps required before beginning this installation process.

Installing a Secondary Director or Standalone Broker

Use the two lists on the Manager type page to select if you want to create a Manager with no Broker, a Manager with a secondary Director, or a standalone Broker. If you install a secondary Director, reconfigure the Manager containing the primary Director; choose Admin > Manager Reconfigure; and enter the secondary Director’s address and port in the corresponding page. This configures the primary Director to recognize the secondary Director and reconfigures the Engine and Driver accordingly.


| 31

Parameters screen shows the installation parameters. To change parameters, restart the installation process with the Start Installation button.

When installing the GridServer Manager on a Unix system, if the installer shows the fully qualified hostname as the Manager name or uses the machine hostname as the full name, this can cause potential routing problems after installation. Change the hostname of the machine with the Custom install option. Go back to beginning of the installation screens and repeat the installation from Step 2, above, entering the correct DNS-resolvable hostname in the Verify Hostname screen.

When satisfied with the parameter values, click Start Installation to begin installation.

8. Restart the Manager

After Manager installation finishes, you are prompted to shut down the application server. On Windows machines, click Quit in the control panel or simply close the console window; in Unix, use the server.sh stop command. Restart the Manager, using the same command used earlier.

9. Create a root account

After restarting Resin, go to http://<yourhost>:<port>/livecluster again. At the prompts, enter a username, password, and password

Figure 9 Verify Setup Parameters screen.


32 |

verification for your initial admin account.

This first account you create is the root account. See the GridServer Administion Guide for more information on the root account.

When upgrading, the username box is pre-filled with the name of the first Configure-level account found in your previous installation. You can use this for the name of your root account, or change it to any other name.

After creating your account, the home page in the Administration Tool appears.

Figure 10 Initial account creation.


| 33

Changing the Web Administration Port

Component messaging and the Web Administration tool use the same network port (8000) by default, and Resin is only configured to listen on that one port.

To change the Web Administration port:

1. During a custom installation or a Manager Reconfiguration, change the Web Administration port to the new port number.

2. Open the file [root]datasynapse\conf\resin.conf and instruct Resin to listen on an additional port by duplicating the following line:

<http server-id="" host="*" port="8000" />

and then changing one of the <http> node entries to the desired port number. For example to change the Web Administration port to 9000, edit the entry so that it looks like this:

<http server-id="" host="*" port="8000" /><http server-id="" host="*" port="9000" />

3. Save the changes to the resin.conf file.

4. Restart the Manager. Resin now listens on two ports. You can verify the change by pointing your browser to the new Web Administration URL on the new port. For the example: http://<manager>:9000

Running Managers From a Different Base DirectoryBy default, all files used by GridServer are stored under the livecluster directory in your applications directory. However, you may want to store all volatile files specific to an installation in a different location. The GridServer base directory refers to the location of these files.

To use an alternate location with the Resin application server:

1. Unarchive the GridServer installation in a directory, for example [GS Manager Root]. Do not start the installation process. Apply any updates, if necessary.

2. Choose the new base directory location for your Manager, and create it. When specifying a new alternate base directory, the base directory cannot be a child directory of the [GS Manager Root] installation directory. Also, the install and alternate base directory cannot be on two different Windows drives (for example, C: and T:.)

3. Make a writable copy of the [GS Manager Root]/conf/resin.conf file, and place it in the base directory.


34 |

4. Set the DS_BASEDIR environment variable to the base directory, and the RESIN_CONF environment variable to the path and filename for the copy of the resin.conf file. You must set these each time you start or stop a Manager, so you can create a small shell script to do this.

5. Start the Manager. When you connect to the GridServer Administration Tool, a Resin Configuration page appears instead of the normal first-time installation page. Follow each of the steps for Resin configuration.

6. Re-start the Manager. The first-time installation page appears. Perform the installation.

7. From then on, set the environment variables whenever you run this Manager. Also, if you change the Engine JRE as described in the GridServer Administration Guide, you must copy it into the different base directory, not the original directory.

Running Multiple Managers From a Single InstallationYou can run more than one Manager on multiple machines from the same shared GridServer installation. To do this, the GridServer [GS Manager Root] is in one shared location, and each Manager runs from its own unique base directory on another unique machine.

To run multiple Managers from a single location, use the procedure in Running Managers From a Different Base Directory on page 33 for each Manager. Start each Manager with server.sh or server.bat, and add the argument -p pidfile, where pidfile is the path and name of an arbitrary file unique to each Manager. For example, start the first Manager with server.sh -p server1 start, the second one with server.sh -p server2 start, and so on. To stop a Manager, use the -p pidfile argument.

Running multiple Managers on a single machine is possible, but not recommended, due to performance issues. Configuring multiple Managers on a single machine requires a unique HTTP port (default 8000), and a unique HTTPS port when using SSL. Using multiple Directors requires unique JDBC listen ports (defaults 9157 and 9158) and a unique Director port (default 2000) for each Manager.

Installing Into a Read-only MountYou can also run one or more Managers from a GridServer installation in a read-only directory, with volatile files stored in another location. To do this, use the instructions Running Managers From a Different Base Directory on page 33 above. For Unix Managers, start the Manager with server.sh, and add the argument -p altdir/pidfile, where altdir is the name of a directory where


| 35

the Manager has read/write permission, and pidfile is the name of an arbitrary file unique to the Manager. For example, you could start the Manager with server.sh -p /nfs/dir/server1, where /nfs/dir is a mount directory, and server1 is an arbitrary file name.


36 |

Installing Manager Licenses

Each GridServer Manager requires a valid license to function. To view your Manager’s license information in the GridServer Administration Tool, click the License Information icon on the Dashboard.

To install the license:

1. Click the License Information icon on the Dashboard.

2. Download the license file from the TIBCO software download site.

3. Click Browse.

4. Find the license file, select it, and then click Open.

5. Click Upload New License.

If the license file is valid, it overwrites the existing license and takes effect immediately. If it has expired or is corrupt or otherwise invalid, an error message appears and your existing license remains in place.


| 37

A Sample Unix rc.d Script

The following is an example of a simple startup script for the GridServer Manager running on a RedHat Linux system:

#!/bin/sh# Startup script for DataSynapse Manager#

# Source function library.. /etc/rc.d/init.d/functions

prog="server"DSBASE=/opt/datasynapseJAVA_HOME=/usr/local/javaexport JAVA_HOME

case "$1" in start) cd $DSBASE ./server.sh start ;; stop) cd $DSBASE ./server.sh stop ;; restart) cd $DSBASE ./server.sh stop ./server.sh start ;; *) echo $"Usage: $0 {start|stop|restart|condrestart|status}" exit 1

esac

exit 0

After creating the above file, place it in /etc/rc.d/init.d/. Your Linux system does not directly run scripts from this directory. Instead, a different directory within /etc/rc.d corresponds to each runlevel of your system. When your system enters a runlevel (for example, during system startup), each script in that runlevel’s associated directory runs and receives the start or stop parameter.

Instead of creating several identical copies of your script, you can create symbolic links in each runlevel directory. Links beginning with K run the script with the stop parameter; those with S run the start parameter. The number at the start of each link dictate the order in which scripts run.


38 |

The following is an example of the links created when installing the above script. These links start the GridServer Manager at runlevels 3 and 5 and stop it at runlevels 0, 1, and 6:

lrwxrwxrwx 1 root root 18 Apr 8 16:26 /etc/rc.d/rc0.d/K02datasynapse -> ../init.d/dsserverlrwxrwxrwx 1 root root 18 Apr 8 16:27 /etc/rc.d/rc1.d/K02datasynapse -> ../init.d/dsserverlrwxrwxrwx 1 root root 18 Apr 8 16:27 /etc/rc.d/rc3.d/S98datasynapse -> ../init.d/dsserverlrwxrwxrwx 1 root root 18 Apr 8 16:27 /etc/rc.d/rc5.d/S98datasynapse -> ../init.d/dsserverlrwxrwxrwx 1 root root 18 Apr 8 16:27 /etc/rc.d/rc6.d/K02datasynapse -> ../init.d/dsserver


| 39

Chapter 4 Windows Engine Installation

This chapter describes how to install GridServer Engines for Windows. You can download an Engine and install it on a machine or transfer it to another machine before installation. You can also use a network installation to install Engines on many machines, or to install the Engine on a Windows Terminal Server for use by multiple PCs.

Topics

• Manual Installation, page 40

• Network Installation, page 41

• Installing Windows Engines in a Non-Default Location, page 42

• Engine Permissions, page 43

• Configuring Permissions for Processor Utilization Mode, page 44

• Configuring Permissions for User Idle Mode, page 45

• Engine Configuration and Management, page 46


40 |

Manual Installation

Install an Engine manually by clicking the Manual Installation link from the Engine Install page. This downloads a file named DSIntranetInstall.exe. Run this file, or save it and move it to another machine.

DSIntranetInstall.exe prompts you to enter a Manager name. Enter the URL of your Primary Director, such as http://hostname.example.com:8000.

Manual Installation NotesA Windows manual Engine installation can fail if the Server Registration screen fails to appear. If this occurs in Windows XP, manually edit the intranet.dat file and specify the Broker URL. For Windows 2003 Server, remote connection requires the console option.

Figure 11 Specifying the Manager URL.


| 41

Network Installation

You can install Engines onto multiple PCs from a shared drive by using a login or update script.

To set up a network installation:

1. Copy the contents of [GS Manager Root]/webapps/livecluster/WEB-INF/engineInstall/win32/network

to a shared directory, such as /share/datasynapse.

2. In a login or update script, include the following:

cd /share/datasynapse install.bat

You can also modify the install.bat file to install Engines in either the system or a user account. install.bat runs the program setup.exe, which accepts username arguments.

The setup.exe program takes a username and password argument before other installation arguments. The username argument has the form DomainName\UserName, or .\UserName if the account belongs to the built-in domain.

For example, the following command silent-installs the Engine and runs the Engine Daemon service with the account .\dave with the password joshua7, writing a log file to c:\datasynapse.log:

Setup.exe .\dave joshua7 -s -f2c:\datasynapse.log

Note that when a user other than Local System runs the Windows Engine Daemon service, the installer grants the user account running the DataSynapse Engine service the Logon As a Service (SeTcbLogonService) right, provided the domain name given does not end with “.”. The user account requires read access to perflib in the registry as mentioned below in Configuring Permissions for Processor Utilization Mode on page 44.

The GridServer Engine downloads a JRE by default. This may be undesirable for larger grids, and you may prefer to include the JRE as part of your deployment. To do so, add the line jre=local to the intranet.dat file. This prevents the installer from downloading and unpacking the JRE. The installer also deletes the install.dat file to prevent future JRE install attempts and behaves as if it successfully downloaded the JRE.


42 |

Installing Windows Engines in a Non-Default Location

The Windows Engine installer installs Engines at C:\Program Files\DataSynapse\Engine by default. You can install in another location manually or with a network script as follows:

1. Edit the setup.iss file in the Windows Engine network installer at [GS Manager

Root]/webapps/livecluster/WEB-INF/engineInstall/win32/network.

2. Change the value of the szDir property to another location.

3. Copy the contents of the directory to the install destination and run install.bat.


| 43

Engine Permissions

Engines installed by an administrator but run by a non-admin user can have permission issues, especially if the Engine removes a registry key and creates it on an update event. This section contains a list of keys created and used by Engines. Use this list to help determine what permissions to set so that Engines function properly.

The following registry keys are used for performance monitoring and require only read access after install:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NetFrameworkHKEY_LOCAL_MACHINE\HARDWARE\DESCRIPTION\System\CentralProcessor\0HKEY_DYN_DATA\PerfStats\\StartStatHKEY_DYN_DATA\PerfStats\\StatDataHKEY_DYN_DATA\PerfStats\StopStatHKEY_LOCAL_MACHINE\SOFTWARE\microsoft\windows nt\currentversion\perflib


44 |

Configuring Permissions for Processor Utilization Mode

If you install an Engine Daemon to run as a Service and the Service logs in as another user, the Processor Utilization mode does not work correctly, because the Engine Daemon cannot retrieve performance data (such as CPU information) from the OS.

To remedy this:

1. Start regedt32 (Click Run... from the Start menu, and type regedt32.)

2. Navigate to the key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WindowsNT\CurrentVersion\

Perflib

3. Right-click the folder named Perflib in the left-hand pane and click Permissions...

4. Add the user that the Engine logs in as, and grant Read access. Do this for each Engine in the Grid.


| 45

Configuring Permissions for User Idle Mode

If you install an Engine Daemon to run as a Service and the Service logs in as another user, the User Idle Mode does not work correctly, because the Engine cannot retrieve UI information from the system.

To use User Idle mode properly, you must run DSHook, a small service that runs in the Local System account and passes information to your Engine Service.


46 |

Engine Configuration and Management

For more information on configuring and managing installed Engines, see the GridServer Administration Guide.


| 47

Chapter 5 Unix Engine Installation

This chapter describes how to install GridServer Engines for Unix. To install Engines on Unix systems, you must download and install an Engine on each system and run a configuration script. The script creates a profile on the Manager that you can use for other Engines, or you can use an existing profile on the Manager.

Topics

• Installing the Engine on page 48

• Running the Engine on page 49

• Read-Only Installation on page 50

• Engine Configuration and Management on page 51


48 |

Installing the Engine

Installing the DataSynapse GridServer Unix Engine comprises unpacking a gzip-compressed tar archive on a Unix system; creating or using a profile on the Manager; and associating the Engine with that profile.

To install an Engine:

1. Download the installation archive to a Unix machine from the System > Engine Install page in the DataSynapse GridServer Administration Tool.

2. Unpack the archive to the directory of your choice. For example, the following extracts the tar file into the directory /usr/local/DSEngine:

cd /usr/localgzip -d -c DSEngineLinux.tar.gz | tar xvf –

3. Run the configure.sh script located in the directory in which you unpacked the archive. If you are installing multiple Engines from a single network mount point, this only needs to be run once per installation.

The following table lists the configure.sh arguments:

If you are intending to run multiple Engines from a shared mount point, you should never attempt to migrate any of those Engines to another Grid, that is, a new Primary Director. Engines running from the same mount point on different Grids is unsupported and will result in unpredictable behavior.

Switch Argument Description

-s Manager:port The domain name or IP address for the Primary Director, and HTTP(S) port.

-P profiles_dir Optional target directory for host-specific directories for native code logging and configuration info to be created. The default value is ./profiles

-l y|n Whether the Primary Director port uses HTTPS.


| 49

Running the Engine

The engine.sh script follows the standard start/stop argument convention for system initialization scripts (“rc scripts”), so you can incorporate it in the start-up and shutdown sequence by inserting appropriate links in the /etc/rc.d files.

The engine.sh arguments are as follows:

If you install a machine without a default route, the Unix Engine returns 0.0.0.0 as the IP address. An IP address of 0.0.0.0 causes communication issues with the Manager. You must ensure that a default route is set for Engines to operate properly.

Switch Argument Description

start n/a Starts the Engine.

stop n/a Stops the Engine.

startfg n/a Starts the Engine, and runs it in the foreground. Useful for monitoring or debugging purposes.


50 |

Read-Only Installation

You can install Engines in a read-only directory using a shared directory for data and work. This configuration enables DDT and a shared directory and disables file updating.

To install in an installation directory that is read-only:

1. In Engine > Engine Configuration > Resource Validation, set the value of Synchronize Resources to False.

2. In Engine > Engine Configuration > Classes, Libraries, and Paths, enter writable locations for the Data and Work directories.

3. In Engine > Engine Configuration > Classes, Libraries, and Paths change the following resource and library directories to shared read-only directories:

— Grid Library Path

— Default JAR and Class Path

— Default Library Path

4. Click Save, to save your changes.

When running configure.sh, make sure the profiles directory is in writable location. If necessary, specify an alternate profiles directory.


| 51

Engine Configuration and Management

For more information on configuring and managing Engines, see the GridServer Administration Guide.


52 |


| 53

Chapter 6 Driver Installation

This chapter describes how to install the GridServer SDK and drivers and configure the drivers.

The Driver is the component that maintains a connection between the GridServer Manager and the client application. The GridServer SDK, available for Windows, Linux, and Solaris, provides these Drivers.

Topics

• GridServer SDK Installation, page 54

• Driver Configuration, page 57


54 |

GridServer SDK Installation

This section describes the GridServer SDK installation. Installing Drivers requires additional steps. To understand your complete installation procedure, read the SDK instructions and the instructions for each Driver you plan to install.

To install the GridServer SDK:

1. In the GridServer Administration Tool, choose Driver > SDK Download, and then click the SDK for your platform to download it.

2. Unzip or unarchive the SDK.

3. Download the driver.properties file from the SDK Download page and copy this file to the config directory of the GridServer SDK. You might need to edit the Manager settings so that the Driver points to your local Manager.

4. Read the following sections for directions on installing Drivers.

The Java Driver (JDriver)The Java Driver, also known as JDriver, consists of a JAR file used with your Java application code.

Perform the following steps to use the JDriver:

1. Ensure that you installed the Java 2 SDK (also commonly referred to as the JDK). You can download it from Sun.

2. Define an environment variable JAVA_HOME that contains the location of the JDK.

Each of the Java examples in the examples directory of the GridServer SDK includes env, build, and run scripts. The examples demonstrate how to properly set classpaths and environment variables to run a Java application using JDriver.

To use the Driver, add the DSDriver.jar file and the config directory of the GridServer SDK to your classpath when running your application.

The C++ Driver (CPPDriver)The C++ Driver, also known as CPPDriver, consists of libraries and include files that are linked with your GridServer application.

Solaris and HPUX systems require GNU tar to unarchive the GridServer SDK.


| 55

Perform the following steps to use the C++ Driver:

1. Set the environment variable DSDRIVER_DIR to the path of the config directory in the SDK.

2. For Windows, add the applicable directory for your complier to the PATH environment variable.

3. For Unix, set the LD_LIBRARY_PATH environment variable to include the applicable directory in the lib directory.

The Parametric Job Driver (PDriver)PDriver, or the Parametric Job Driver, is a Driver that can execute command-line programs as a parallel processing job using the GridServer environment. This enables you to take a single program, run it on several Engines, and return the results to a central location, without writing any new code.

Perform the following steps to use PDriver:

1. In the pdriver directory of the SDK, run the setenv.bat or setenv.sh script before you use the Driver. This script sets the path, DSDRIVER_DIR and DS_SDK_DIR environment variables for Drivers. The best way to run the script is to run it from a login script. For Unix, run the setenv script from the pdriver directory with a source setenv.sh.

Note that PDriver is not supported for the Solaris x86 32-bit platform. For 64-bit Windows, use the version of PDriver included in the 32-bit Windows SDK

Running PDriver on Windows Engines

The Windows Pdriver.dll was compiled using Visual C++ 6, so Windows Engines must use the VC 6.0 version of the C++ bridge. PDriver uses the default library path in the Engine Configuration, typically ./resources/win32/lib, so you must make sure that DSBridgeVC6.dll is the only bridge in that directory. If you have other Services that require other bridges, you must use Grid Libraries.

Running PDriver with Linux

A number of different compilers are available for the various Linux distributions, and not all platforms support all compilers. Because of this, each supported Linux platform has a compiled libpdriver.so file. However, PDriver uses the default library path in the Engine. To deploy PDriver, deploy the correct C++ bridge library and PDriver library for the path. For example, on an Engine that runs on a platform that only supports GCC 3.0, deploy libpdriverGCC3.so and libdsBridgeGCC3.so to resources/linux/lib/gcc3, and set the Default Library Path to ./resources/linux/lib/gcc3.


56 |

Using PDriver

To run a PDriver script file, invoke the PDriver binary and pass the PDriver script file as the first argument. For example, on Unix systems:

pdriver examples/example.pds

Running pdriver or PDriver.exe without a PDS argument provides a usage message.

The examples directory contains several example PDriver script files.

The .NET DriverThe .NET Driver consists of an assembly that includes classes for creating and managing Services from .NET. The .NET Driver is available only for Windows.

Perform the following steps to use the .NET Driver:

1. Find the GridServerNETClient.dll in the NETDriver directory and link this assembly to your application.

2. Set the environment variable DSDRIVER_DIR to the path of the config directory in the SDK.

COM DriverThe COM Driver enables an application using the Component Object Model architecture to access GridServer, enabling distributed parallel execution of the application on a Grid of Engines. The Driver includes an example, an Option Evaluation spreadsheet in Excel that uses GridServer for its calculations. The COM Driver is available only for Windows.

Perform the following steps to install the COM Driver:

1. In the COMDriver directory of the SDK, double-click the DSCOMDriverInstall.exe to start the installer.

2. After the InstallShield welcome screen, click Next.

3. Click Browse to select a location for the COM Driver. The default location is C:\DataSynapse\DSCOMDriver. Click Next.

4. Enter the address of the primary and secondary Directors, in the form hostname:port. For example, http(s)://server1.mycompany.com:8000. You can proceed without filling in any values, but you must later specify your Directors by editing the driver.properties file. Click Next.

5. Click Finish.


| 57

Driver Configuration

Driver configurations reside in the driver.properties file. You can download this file from the SDK Download page; copy it to the config directory of the GridServer SDK. When you install Manager, the driver.properties file contains hostnames for the primary and secondary Director. To change the default values, edit the driver.properties file. For example, to add a username and password for authentication, change the primary and secondary Director, change the Broker Timeout, and so on.

You can move the driver.properties file to another directory. For Java, add the new directory to your classpath. For C++, .NET, and PDriver, the DSDRIVER_DIR environment variable must be set to the location of this directory. For PDriver, edit the setenv.bat or setenv.sh script to set the DSDRIVER_DIR environment variable.

If you use the following characters in properties in the driver.properties file, precede each with a backslash: #, !, # =, \, and :

Backslash characters in hostname or directory properties receive special handling on Windows Drivers. The first backslash, indicating the root directory, translates as the current Windows drive. Other backslashes are ignored. Forward slashes translate as backslashes.

For example, to set a directory to c:\sdk\log, use /sdk/log in the driver.properties file. To use a UNC path such as \\homer\job1-dir, use //homer/job1-dir in the driver.properties file.

You can also set Driver properties programatically with the API. When you do this, the driver.properties file is unnecessary. At minimum, set DSPrimaryDirector and DSSecondaryDirector (or set them both to the same hostname when using a single Director); other properties use the default settings.

If your username and/or password is non-ASCII, you must express it in Unicode converted format rather than as the Unicode characters. For example:DSUsername=\u6B21\u306E\u30E6\u30FC

Configuring Drivers with Multiple Network InterfacesIn some network configurations, on a PC with multiple network interfaces, a Driver might default to using the incorrect interface. To configure the Driver to use a different network interface, set the DSLocalIPAddress property to the IP number of the correct interface. For example:

DSLocalIPAddress=192.168.12.1


58 |

Multiple Driver InstancesServices can fail if you enable Direct Data Transfer and write a script that instantiates multiple Drivers from the same driver.properties file with the same port number. The first Driver opens a web server listening to the defined socket. Subsequent Drivers do not open another web server as long as the first Service is running, but can continue running by using the first Service’s server for direct data. However, when the first Service completes, its server terminates, causing subsequent Services to fail.

You can avoid this problem by writing a shell script to create Services, each with its own Driver running from its own Java VM. Your script must provide a different port number for the DSWebserverPort property normally set in the driver.properties file. To write a shell script for this situation, you can remove the DSWebserverPort property from the driver.properties file and assign a unique port number for each iteration.

More than one Driver can share the same directory. However, if you do so you must set a unique DSCacheRootDirectory for each Driver if using GridCache. Also, if using long-running services, you must set a unique DSWebServerDir property so that one Driver’s file cleaner does not clean another session initialization data.

Prohibiting Driver Version MismatchYou can configure the Manager to enable or prohibit Driver login if the Driver has a different version than the Manager. This can be changed in the Administration Tool at Admin > Manager Configuration > Admin with the Allow Driver Version Mismatch property. This is enabled by default. (Previous versions disabled this by default.)


| 59

Chapter 7 Verify Installation

After installing a GridServer Manager and one or more Engines, you can test your installation by submitting a test Service and watching its progress in the GridServer Administration Tool.

Topics

• Submitting a Service Test, page 60

• Monitoring a Service Test, page 61

• Troubleshooting, page 62


60 |

Submitting a Service Test

A Service Test can run a Linpack benchmark that you can use as a basic test for your Grid.

To submit a Service Test:

1. Make sure at least one Engine is logged in to your Manager.

2. Log in to the GridServer Administration Tool and select Services > Service Test.

3. Click Submit to send the Linpack Test with default values. You can also change the number of Tasks or Duration to make a Service that takes longer to complete.

4. The Services Admin page appears. From this page, you can monitor the Service’s progress.


| 61

Monitoring a Service Test

After you submit the Service Test, you can monitor its progress to ensure that your Engine is taking tasks and returning results. While the Service Test is running, you can also view other pages for more information:

• Select Manager > Broker Admin. A list of available Brokers appears, along with the number of busy, idle, and total Engines reporting to that Broker.

• Click the Broker Monitor icon on the Dashboard. A screen appears showing four interactive graphs: the Engine Monitor, Service Monitor, Task Monitor, and System Monitor. The System Monitor graph shows memory and thread activity.

• Select Engine > Engine Admin for a list of all Engines and their status. Figure 12 The Broker Monitor.


62 |

Troubleshooting

If the Service Test does not function, or you have other issues relating to your installation, consult the GridServer Administration Guide and online help in the Administration Tool.


| 63

Chapter 8 Uninstalling GridServer

This chapter describes how to uninstall GridServer. The uninstall procedures for the Windows operating system and the Unix operating system differ.

Topics

• Uninstalling an Engine, page 64

• Manual Uninstall, page 64

• Uninstalling a Manager, page 65


64 |

Uninstalling GridServer on Windows Systems

Uninstalling an EngineTo uninstall an Engine on a Windows system:

1. If you engaged the Engine manually, right-click the DataSynapse icon in the Task Tray and select Stop. The DataSynapse Icon turns red.

2. Right-click the red DataSynapse icon in the Task Tray and select Exit.

3. In Windows, select Start > Control Panel > Administrative Tools > Services. Click DataSynapse Engine to stop the application as a Service.

4. In Windows, select Start > Control Panel > Add/Remove Programs. Remove the DataSynapse Engine. Follow the onscreen instructions through the uninstall.

When the uninstall finishes, delete the remaining Engine directories from your disk. (The default location for these files is C:\Program Files\DataSynapse.)

Manual UninstallYou can remove DataSynapse Engines using silent installation scripts similar to those described in Network Installation on page 41. However, instead of the install.bat script, use the uninstall.bat script.

To uninstall an Engine manually:

Figure 13 Stopping the Engine from the Engine Menu

Figure 14 Exiting the Engine from the Engine Menu


| 65

1. Change directories to the shared network installation directory containing the uninstall.bat. If this directory no longer exists, you can re-copy the contents of [GS Manager Root]/webapps/livecluster/WEB-INF/engineInstall/win32/network

to a shared directory.

2. Stop the Engine. To script this, write a batch file that contains the command net stop "DataSynapse Engine" before the uninstall command.

3. Run uninstall.bat from the shared network installation directory.

Uninstalling a ManagerTo uninstall a Manager with Resin on a Windows system:

1. If the Manager is installed as a Service, select Start > Control Panel > Administrative Tools > Services.

2. Click DataSynapse Manager and click the Stop icon to stop the application.

3. Open a command line, go to the GridServer Manager root directory, and issue a server remove name command to uninstall the Server named name. Omit name if you did not name your Manager during installation.

4. In the [GS Manager Root]/webapps directory, remove the livecluster directory and its contents. You can also remove the entire [GS Manager Root] directory containing GridServer and the application server.

Figure 15 Stopping a Manager installed as a Windows Service.


66 |

Uninstalling GridServer on Unix Systems

To remove a GridServer Manager or Engines on a Unix system:

1. Stop the Engine or the Broker (engine.sh stop or server.sh stop).

2. Remove any modifications you made to startup files, typically located in /etc/rc.d directories.

3. Remove all files in the installation directory.


| 67

Chapter 9 Upgrading GridServer

This chapter explains how to upgrade GridServer. It contains a GridServer Upgrade Checklist, which explains what to do before, during, and after your new GridServer installation to ensure carrying over old values to the new installation, when possible. This chapter also describes any changes in requirements for running GridServer 5.1 and a list of API changes between GridServer 5.1 and earlier versions.

Topics

• Requirements Changes, page 68

• Other Changes, page 70

• GridServer 5.1 Upgrade Checklist, page 71

• Engine Upgrade, page 74

• Driver Upgrade, page 75

• Default Engine Configuration Changes, page 76

• Default Manager Configuration Changes, page 77

• Incompatibilities Due to API changes, page 78

• Mixed-Version Deployments, page 79

• Rolling Upgrades, page 80


68 |

Requirements Changes

Please see the system requirements on the TIBCO Customer Support Website to ensure that your software and hardware meet the minimum system requirements. Below is a list of some requirements that have changed since GridServer 5.0. However, make sure to review the full list of requirements.

Java RequirementsManagers and Drivers require Java Virtual Machine or 1.5.0_07 or greater. 1.4.2_12 has been deprecated.

GridServer now requires the Oracle Java SDK JDK SE 7 for Managers. If using the Java Driver, Oracle Java SDK JRE 6 or JRE 7 is required; support for JRE 6 is deprecated. Support for all other versions has been discontinued.

.NET Framework Requirements• .NET 4.0 is now supported.

• .NET 1.1-3.0 support has been discontinued.

C++ Requirements• For Solaris, the Forte 7 compiler is no longer supported. If you compiled your

code with Forte 7, you will need to recompile and use the CC libraries.

• The naming of the studio11 platform has been removed; the platform is now known as “CC”. If your code has a dependency to studio 11, you must either rebuild, or change the name of the CC library to studio11. If any Engine Configurations are set to studio11, you must set them to CC.

• GCC 3.2 is no longer supported.

• VC 6 and VC 7.1 are no longer supported.

• VC 8 support is deprecated.

Database Requirements• Oracle 11g are now supported for reporting databases; Oracle 9i and 10g

support has been discontinued. In the Manager configuration, the reporting database type for oracle11g has been changed to oracle.

• Sybase 12 is no longer supported.


| 69

• DB2 is no longer supported.

• Microsoft SQL Server 2000 is no longer supported.


70 |

Other Changes

• The StreamJob API is no longer supported.

• API Additions for Broker Spanning may require recompilation of native libraries if they link against the Admin API.

• GridServer 4.2 had an issue where Grid Library dependencies were incorrectly loading using an inverse depth-first traversal. GridServer now uses a proper depth-first traversal. Set the java system property: com.livecluster.engine.EngineResourceManager.loadOrder42=true

in the Engine Configuration to preserve the version 4.2 order if necessary.

• In the reporting database, the users table has been removed. The table is no longer created on new installs, but the schema is not changed for upgrades; the table is simply no longer updated. You can optionally drop the table after upgrade.

• The deprecated Reporting Database cleaner has been removed. Database cleanup can no longer be performed from GridServer. Consult your database’s documentation for more information on best practices for database cleanup.


| 71

GridServer 5.1 Upgrade Checklist

You can migrate settings from your previous version of GridServer to your new version of a GridServer installation, but it’s important to not install on top of your previous installation. Instead, shut down your old Manager, and rename the old installation directory. You can then install GridServer 5.1 in the same location. Later in the install, you supply a path to the renamed old installation so settings can be copied.

Note that Manager configuration values, such as backlog, max queue, log level, timeout seconds, and so on, do not migrate to the new version during a Manager upgrade. However, an upgrade.log is generated that lists all changed configuration values, so that you can restore your settings.

Prior to Upgrade • If you have previously used the system classpath in your Engine

configuration and deployed the DSEngine.jar file to Engines, remove the deployed DSEngine.jar and let Engines update before upgrading the Manager. After the Manager upgrade, deploy the new DSEngine.jar to Engines.

• If you have already upgraded without deleting the old DSEngine.jar, you must turn off Engine version check; In the GridServer Administration Tool, choose Admin > Manager Configuration > Admin, and set Allow Engine Version Mismatch to True, which enables Engines to log in and download the new DSEngine.jar. Once they have, you can turn on the version check by setting Allow Engine Version Mismatch to false.

After Stopping the Manager • When running GridServer as a Windows service, remove the service prior to

upgrading.

During Installation • For Installation Type, choose Custom, Manager Upgrade.

• Under Previous Base Directory, enter the livecluster directory of your previous installation, such as /datasynapse.last/webapps/livecluster.

• If you have installed a previous version of GridServer with an alternate base directory and you upgrade to a new version, you must use the same directories for the new installation.


72 |

• When upgrading from an alternate base directory to an alternate base directory, you can enter only the base directory, instead of the livecluster directory, such as /datasynapse.alt instead of /datasynpapse.alt/webapps/livecluster.

• If you modified the manager.keystore, then before proceeding to upgrade, you must first copy WEB-INF/certs in the old DSWebappDir to WEB-INF/certs in the old alt-based DSBaseDir.

• You must generate the server.keystore file before installing a SSL server. See “Enabling HTTPS on the Application Server” in the GridServer Administration Guide.

• If you made changes to the default database values in the previous installation, you must re-enter them, as all database values reset to their default value. Confirm all database values, especially when running an external reporting database. All other values carry over.

After Installation• Check the upgrade.log file in the livecluster/WEB-INF/log directory. Any

changes made from the default in the prior version are logged. An upgrade restores all values to default, so you might wish to restore these changes if they still apply.

• The Engine balancer configuration returns to the default—Weight-Based—option during upgrade. However, this is not noted in the upgrade.log file. If your Engine balancer configuration was previously set to Home/Shared, you must reconfigure this option. Go to Admin > Manager Configuration > Engines and Clients and select Home/Shared from the Engine Balancer drop-down menu.

• To upgrade an external reporting database schema from a previous version of GridServer, run the upgradedb.sh or upgradedb.bat script located in [GS Manager Root]/webapps/livecluster/WEB-INF/etc/db.

• An issue was corrected in which updating information on a user from the Edit User page or Admin API resulted in duplicate entries being created in the internal repository. These spurious entries were ignored, so there was no functional issue. This is fixed only for new installations, not for existing installations on which the Service Pack is applied.

To apply the fix, open [GS Manager Root]/webapps/livecluster/WEB-INF/db/hsqldb/initial

.script, and change this line:

CREATE TABLE users ( username VARCHAR(255) NOT NULL, user_access INT, user_info LONGVARCHAR, personalization LONGVARCHAR, roles LONGVARCHAR );


| 73

to:

CREATE TABLE users ( username VARCHAR(255) NOT NULL, user_access INT, user_info LONGVARCHAR, personalization LONGVARCHAR, roles LONGVARCHAR, primary key (username) );

Do the same for [GS Manager Root]/webapps/livecluster/WEB-INF/db/internal/Inter

nal.script.


74 |

Engine Upgrade

• If there are multiple Unix Engines running from the same shared directory, the Engines do not auto-update to the latest version. You must manually install the new Engine once into the shared installation directory, which causes all Engines to run the latest version.

• Engine configurations whose LIB_DIR specify absolute paths containing .NET assemblies do not work after upgrading. Change the absolute paths to relative paths.

• For Unix Engines, bin/invokeRA cannot be automatically upgraded. After upgrading to 5.1, you must manually copy bin/invokeRA from a 5.1 installation to the upgraded Engine, and follow the instructions in “Using Run-As” in the GridServer Administration Guide.

• During upgrade, Engine configurations are copied to the updated grid but not checked for incompatibility with the upgrade. For example, gcc3 for Linux is no longer supported. However, during upgrade, this value is maintained for any Engine specifying gcc3 as the value for Engine GCC built version before the upgrade. You must change this Engine configuration setting yourself; go to Engine > Engine Configuration in the Classes, Libraries, and Paths section.


| 75

Driver Upgrade

• Download the new version of the GridServer SDK in the GridServer Administration Tool.

• Make sure that all Drivers are upgraded. This simply involves replacing the libraries or executables with the new version.

• If you have existing CPPDriver applications, relink them with the new libraries included in the SDK.

• On the Driver side, link your code with the dsUtil library. Link Engine-side Service code with the dsUtil library if it uses any exception classes.

• If you have existing .NET applications, you must change the reference to the new GridServerNETClient.dll and rebuild.

• In any Makefiles, for GridServer 5.1, there are new library versions for the following Unix files:

• libcurl.so.4 replaces libcurl.so.3


76 |

Default Engine Configuration Changes

No changes between 5.0 and 5.1


| 77

Default Manager Configuration Changes

No changes between 5.0 and 5.1


78 |

Incompatibilities Due to API changes

GridServer 5.1No incompatibilities.

GridServer 5.0• BasicEngineDiscriminator, PropertyDiscriminator, and

PropertyScoringDiscriminator are deprecated. Use SchedulingConditionFactory instead.

• Custom implementations of Discriminator and ScoringDiscriminator are no longer supported.

• In UserDatabaseHook, UserData.[set/get]Roles(String[] roles)was added; UserData.[set/get]Access(int access) was deprecated.

• LiveCache is no longer supported. Use GridCache instead.

• The static writeProxy convenience methods on ServiceBindingStub are no longer supported.

• The Service methods to use GridServer 4.1-style discriminators are no longer supported.

• Propagator and Dataset are not available in GridServer 5.0.

• WS-I compliance changes can affect existing API for Command and Dynamic Library services. Object or Object[] as arguments or return types are no longer supported for Web Services and Grid Server generated proxies.

• Customer C++ code that uses the GridCache API and was built against a previous releases of GridServer libraries requires recompilation.


| 79

Mixed-Version Deployments

Mixed-version deployments are grids that consist of both GridServer 5.1, and 5.0 Brokers. This is an allowed configuration, as a convenience for large Grids that cannot upgrade all Brokers at once. You must address the following issues when running mixed-version deployments:

• The mixed-version Grid requires GridServer 5.1 Directors. While you can run GridServer 5.1 Directors with 5.0 Brokers, you cannot do the reverse.

• You must disable client version checking for Engines, Drivers, and Brokers by selecting Admin > Manager Configuration > Admin.

• Hard-partitioning Engines is recommended so that Engines only go to one version of the Broker. Do this with Broker routing or home/shared Brokers. If you don’t do this, Engines perform additional restarts when changing versions.

• You must deploy both versions of the C++ Bridge Grid Libraries via the Primary Director. If you upgraded the Director, the older bridges may already be there, but if the Director is a new installation you must copy them from your 5.0 Managers. The Engines automatically choose the proper library based on the Broker version. Because both versions of the C++ Bridges are used, gridlibs must also be used on an older Broker if the code is native, rather than using the standard resource deployment.

Mixed-Version IncompatibilityGridServer 5.1 is backwards compatible with GridServer 5.0 Drivers, however, the following known instances of incompatibility exist:

• Propagator and Dataset are not available in GridServer 5.0.

• LiveCache is no longer supported. Use GridCache instead.

• PDriver is not supported since it uses LiveCache.

• You must recompile Engine side C++ code that uses the GridCache API against GS 5.1 libraries.


80 |

Rolling Upgrades

Use the following procedures to install an update to a large grid (a grid with a large number of Engines and several Brokers) in situations where you cannot permit grid-wide Engine restarts and interruptions in Service availability. These instructions enable Services already deployed on components using a previous version of GridServer to continue running as other components on the grid are updated.

Prerequisite Actions

For all Managers:

1. Bring all Managers up to the required hotfix level, as described in Prior to Upgrade on page 71.

2. Confirm that all GridServer Managers are at that level. On the Primary Director, you can get the versions of all Brokers on the Manager > Broker Admin page. To find the version of the Directors, click the Product Information link at the bottom of the Administration Tool.

3. In each Engine Configuration, confirm that Logoff Engines on Daemon Logoff is set to false (the default setting). This prevents unnecessary Engine restarts when the Director is restarted.

4. On each Broker, go to Admin > Manager Configuration > Admin. Set Daemon Upgrade From Broker to false. This will prevent all Daemons from restarting to upgrade when the Primary Director is upgraded.

5. On each Director, go to Admin > Manager Configuration > Admin. Confirm that Daemon Upgrade From Director is false. (This is the default and would rarely be true.)

6. To assist in the event of any issues, set the logging levels on all Managers and Engines to Fine.

Upgrading a GridNote that each Manager upgrade procedure does not make any modifications to the previous installation. If required, you can use this directory to roll back the upgrade.


| 81

Task A Primary Director Upgrade

1. Shut down the Primary Director. The Engine Daemons move to the Secondary Director and the Engine Instances (which may be running tasks) continue without interruption.

2. Upgrade the Primary Director.

3. Start the Primary Director.

4. Verify the the following Director and Broker mismatch controls are True: Admin > Manager Configuration > Admin > Version Management >Allow Director Version Mismatch and Admin > Manager Configuration > Admin > Version Management >Allow Broker Version Mismatch.

5. Check that all the Brokers are logged in to it at Manager > Broker Admin. The Engine Daemons will move to the Primary Director. The Engine Instances will not restart.

Task B Secondary Director Upgrade

Follow the above procedure for the Primary Director. Shut down the Secondary Director and upgrade.

Task C Broker Upgrades

Failover Brokers should be upgraded after regular Brokers.

For each Broker:

1. Shut down the Broker. Within a few minutes Engines and Drivers will migrate to a Failover Broker.

2. Upgrade the Broker.

3. Start the Broker. Verify that it logs in to the Directors.

4. Verify that Admin > Manager Configuration > Admin > Version Management > Allow Driver Version Mismatch is True.

5. Within a few minutes Engines and Drivers will migrate back.

Task D Upgrade the Engine Daemons

At this point, the Grid has been updated, but Engine Daemons are still at the previous version. Daemon upgrades result in Engine restarts, so do the following on each Broker when the time is appropriate:


82 |

1. On each Broker, go to Admin > Manager Configuration > Admin. Set Daemon Upgrade From Broker to true.

The above step needs to be done as soon as possible.


| 83

Appendix A Database Configuration

The GridServer Manager can use a reporting database to store tables containing statistics for Services, tasks, Engines, and other records. You can configure GridServer to use an enterprise-grade database from another vendor for the reporting database. You can use the HSQLDB database that is included with GridServer as a test reporting database for demonstration purposes.

If a Manager is already running against a different third-party database and you do not migrate the contents of that database to the new database, you will lose all data. To avoid losing data, first establish the database you plan to use; then afterward, initialize Manager.


84 |

Configuring the Reporting Database

To configure the reporting database, first install your Manager; second, configure the database; and third, configure the Manager to use the new database. Then, restart the Manager. See the GridServer readme for a list of supported databases.

Task 1: Install the Manager:

1. Install and configure your GridServer Manager. Restart the Manager after completing the installation.

2. Ensure that the tables.<db>.sql file needed by the createdb script is in the [GS Manager Root]/webapps/livecluster/WEB-INF/etc/db directory.

Task 2: Configure the database (skip these steps for HSQLDB):

1. Set the CLASSPATH on the Manager containing the Director that communicates with the DB. The CLASSPATH must include the database driver JAR files applicable to your database. For example, to create an MSSQL2k db in a unix shell:

export CLASSPATH=[JDBCDriver]/msbase.jar:[JDBCDriver]/mssqlserver.jar:[JDBCDriver]/msutil.jar

replacing [JDBCDriver] with the actual path to the directory containing your driver JAR files.

2. Run the createdb script provided in [GS Manager Root]/webapps/livecluster/WEB-INF/etc/db directory on your Manager. Pass the name of the database properties file as an argument. Before you run the script, change the property file settings to match those of your database.

Task 3: Configure the Manager:

1. Log in to the GridServer Administration Tool with an account that has a Security Role with the Manager Reconfigure feature enabled.

2. Choose Admin > Manager Configuration > Database.

3. Configure the values in the Reporting Database Connection section using the appropriate table below. Note that hostname is the hostname and database is the name of the database.

Property Value

Oracle 11g:

URL jdbc:oracle:thin:@hostname:1521/database

Driver oracle.jdbc.OracleDriver


| 85

4. Copy the corresponding JDBC driver’s JAR file into the Manager’s [GS Manager Root]/webapps/livecluster/WEB-INF/lib directory.

5. Restart the GridServer Manager.

Transaction Isolation TRANSACTION_READ_COMMITTED

Database Type oracle

Sybase Adaptive Server Enterprise 15:

URL jdbc:sybase:Tds:hostname:5000/database

Driver com.sybase.jdbc2.jdbc.SybDriver

Transaction Isolation TRANSACTION_SERIALIZABLE

Database Type sybase12

Microsoft SQL Server:

URL jdbc:sqlserver://hostname:1433;DatabaseName=dbName;SelectMethod=cursor

(SelectMethod=cursor is required)

Driver com.microsoft.sqlserver.jdbc.SQLServerDriver

Transaction Isolation TRANSACTION_SERIALIZABLE

Database Type mssql

Property Value


86 |

Third-Party Database Known Issues

Microsoft SQL ServerSetting the SelectMethod property to “Direct” produced errors in Microsoft SQL Server 2005 JDBC Driver 1.1. Set SelectMethod to “cursor” to prevent direct query connection cloning from conflicting with the GridServer Manager’s connection pooling scheme.

The SelectMethod=cursor property is required only when using Microsoft’s Type 4 JDBC drivers. Other drivers are untested.

OracleUse the Oracle 11g server with Type 4 drivers. Oracle’s documentation suggests that their OCI (Type 2) drivers do not properly support Timestamp data types. The GridServer Manager uses Timestamp data types extensively.

The Oracle schema uses CLOB data types for some fields.


| 87

Appendix B Kerberos Support

Kerberos-Based Single Sign-On (SSO) provides Kerberos support for GridServer Software. This support lets you integrate GridServer with existing Kerberos SSO solutions in your network environment.

This chapter of the Kerberos Support Guide describes requirements for installing and using the Kerberos SSO feature. The chapters that follow describe how to configure and use Kerberos SSO support.

Topics

• Required Knowledge, page 88

• Required Software, page 89

• Enabling SSO on the GridServer Administration Tool, page 90

• Configuring JDriver to use Kerberos, page 96


88 |

Required Knowledge

This appendix presumes that you have a DataSynapse GridServer Manager running and know the hostname, username, and password. If you do not, refer to this GridServer Installation Guide or contact the administrator responsible for the installation.

This appendix presumes familiarity with the following:

• GridServer Administration

• Windows network administration

• Quest Single Sign-On for Java software (QSJ) (formerly Vintela Single Sign-On for Java) and Quest® Authentication Services software (QAS) (formerly Vintela Authentication Services software).

Consult version-specific documentation for additional instructions on using or configuring any external application.


| 89

Required Software

The following software is required:

Any differences or limitations from standard GridServer requirements are noted in the table above.

Software Comments

Operating SystemAny version of Windows that supports the current version of GridServer.

Windows Command Line Toolsktpass.exesetspn.exe

Check for these utilities, along with other Support Tools, on the product CD for your version of Windows. They are also available from the Microsoft® Download Center.

BrowserWindows Internet Explorer 6.0 or newer

Applications from Quest SoftwareQuest Single Sign-On for Java 3.2 or newer (QSJ)

Quest Authentication Services (QAS)

Provides server-side SPNEGO authentication support. Formerly Vintela Single Sign-On for Java.Allows Linux/Unix machines to log in to Active Directory. Formerly Vintela Authentication Services.


90 |

Enabling SSO on the GridServer Administration Tool

GridServer Kerberos SSO support authenticates users using their workstation login credentials, allowing users to access the GridServer Administration Tool without the need to log in. Once you sign on to your computer, you can access the GridServer web interface without logging in separately to GridServer.

To enable this functionality, complete these tasks:

• Configure Windows Active Directory to work with GridServer.

• Modify and configure GridServer for single sign-on.

• Configure LDAP in GridServer.

• Install and configure the Quest Single Sign-On for Java software (QSJ).

• Configure Internet Explorer to allow single sign-on.

Note that the instructions below assume you have the QSJ software and documentation. This application is required to enable SPENEGO SSO logins to GridServer.

Configuring Windows Active Directory for QSJFollow the instructions below to:

• Configure the Windows Active Directory to work with GridServer on your site’s domain controller machine, that is, the machine hosting Windows Active Directory.

• Set up an Active Directory service user account for GridServer and assign appropriate Service Principal Names (SPNs) for that user. For additional information, see the QSJ or Windows Active Directory documentation.

Create a New Service User Account

You can use an existing user account for the Service if that account has the Password Never Expires option selected. To create a new service user account, follow the steps below:

1. On the machine with the Domain Controller for Active Directory, select Start > Programs > Administrative Tools > Active Directory Users and Computers.

2. Select the Users folder. From the Action menu select New > User.

3. Provide a Name and a Logon Name for the new user. For the Name, use standard alphanumeric characters with no whitespace. For example,


| 91

[newGridUser]. This account must be the same account you use to run GridServer.

4. Click Next.

5. Provide a Password for the new user. Select the Password Never Expires option.

6. Click Next and Finish.

Map Service Principal Names

Follow the instructions below to map one or more Service Principal Names. The first mapping must be the fully qualified domain name for the server. Mapping additional SPNs lets you specify alternate domains or shorter versions of the domain name so that SSO works correctly when users supply those URLs rather than the fully qualified URL.

1. Open a Windows command window:

2. Run ktpass.exe with the following arguments:ktpass -princ HTTP/[your-GridServer-machine.your-subdomain.your-domain@YOUR-KERBEROS_REALM] -mapuser [newGridUser]

3. Optionally, define several additional SPNs for referring to the server machine. In the Windows command window, run setspn.exe as follows:

setspn -A HTTP/[your-GridServer-machine] [newGridUser]

setspn -A HTTP/[your-GridServer-machine.another-subdomain] [newGridUser]

Enabling TGT

To enable TGT on the client, see the following Microsoft KB article: http://support.microsoft.com/kb/308339.

Configuring LDAP in GridServerUse the GridServer Administration Tool to configure LDAP support in GridServer to allow Active Directory as a user database. Configure Active Directory authentication and a GridServer security role. For more details consult the GridServer Administration Guide.


http://support.microsoft.com/kb/308339

92 |

Configure for Authentication

To configure GridServer for Active Directory authentication, complete the following steps:

1. From the GridServer Administration tool, select the Users > Authentication.

2. Fill in the fields on the configuration page as indicated. You can leave any other fields empty.

3. Click Save.

Configure the Security Role

To configure the security role:

1. From the GridServer Administration tool, select Users > Role Admin.

2. Select a role from the Security Role list, for example Configure. The role page appears.

3. Fill in the LDAP Group Name field as follows:

cn=Administrators,cn=Builtin,[your-base-DN]

For example, dc=[your-sub-domain],dc=[your-domain],dc=com

Name of Field Contents Description

Authentication Mode LDAP

Provider URL(s) ldap://[your-active-directory-machine.your-subdomain.your-domain].com:389

Authentication Scheme simple

Username cn=administrator,cn=Users,[your-base-DN]For example, dc=[your-sub-domain],dc=[your-domain],dc=com

Password [YourDomainAdministratorAccountPassword]

User Search String Format (&(objectclass=user)(sAMAccountName={0}))

User Search Base cn=Users,[your-base-DN]For example, dc=[your-sub-domain],dc=[your-domain],dc=com

User Group Attribute memberOf


| 93

4. Click Save.

Installing and Configuring QSJAfter installing the Kerberos patch and configuring LDAP in GridServer, install, configure, and enable the QSJ software. Doing so enables SPNEGO SSO logins to GridServer. For more details, consult the QSJ documentation.

1. Shut down GridServer before installing QSJ.

2. To install QSJ, copy vsj-standard-3.2.jar, and winSSPI.dll to the following directory: [GS Manager Root]\webapps\livecluster\WEB-INF\lib.

3. Copy the QSJ license file, vsj-license.jar, to the [GS Manager Root]\webapps\livecluster\WEB-INF\lib directory.

4. Edit the following file to provide QSJ configuration information to GridServer:[GS Manager Root]\webapps\livecluster\WEB-INF\web.xml

Add the XML provided below to your web.xml file under the <web-app> node, substituting values appropriate for your environment.

<filter> <filter-name>authFilter</filter-name> <filter-class>com.wedgetail.idm.sso.AuthFilter</filter-class> <init-param> <param-name>idm.realm</param-name> <param-value>[YOUR_KERBEROS_REALM]</param-value> </init-param> <init-param> <param-name>idm.princ</param-name> <param-value>[HTTP/server.yourdomain.com]</param-value> </init-param>


94 |

<init-param> <param-name>idm.allowNTLM</param-name> <param-value>false</param-value> </init-param> <init-param> <param-name>idm.allowUnsecured</param-name> <param-value>[true-or-false-as-appropriate-for-your-environment]</param-value> </init-param> </filter> <filter-mapping> <filter-name>authFilter</filter-name> <servlet-name>admin-controller</servlet-name> </filter-mapping><filter-mapping>

<filter-name>authFilter</filter-name> <url-pattern>/director/PublicDriverChannel</url-pattern></filter-mapping>

The next step describes two options for specifying your QSJ password. Your choice affects how you modify the XML.

5. Configure QSJ passwords in the web.xml file. You can do this in either of the following ways:

— Specify an idm.password setting in the web.xml file. This option is fine for initial testing and configuration, but because the password appears in clear text in the web.xml file, it is not secure enough or recommended for production environments.

— Use a keytab file containing encrypted versions of passwords, and edit the web.xml file to include the name of the keytab file. This option is harder to change, but more secure, and therefore recommended for production environments.

For details on both password options, see the QSJ documentation.

6. Restart the GridServer Managers.

Running GridServer as Service Principal UserTo run GridServer as the Service Principal User:

1. Log in as the user you created earlier when mapping the Service Principal Name, for example [newGridUser].

2. Start GridServer from the command line. Or, if you set up GridServer to run as a service, supply the SPN mapped username and password.

For details on setting up GridServer as a service, see the GridServer Installation Guide.


| 95

Configuring Internet ExplorerTo configure Internet Explorer, add the URL of the GridServer web interface to Explorer’s list of trusted local sites on all individual workstation machines.

1. Start Windows Internet Explorer.

2. Select Tools > Internet Options. The Internet Options dialog appears.

3. Select the Security tab.

4. Select Local Intranet, click Sites.

5. Click Advanced.

6. Type the URL of your GridServer Broker. For example, http://server.yourdomain.com:8000.

7. Click Add to add it to the list of trusted local intranet sites.

8. Click Close. Click OK to save this change to your advanced settings. Click OK to exit the dialog and save changes.

Verifying a Successful ConfigurationIf your configuration is successful, you can now access the GridServer web interface without going through the login page.


96 |

Configuring JDriver to use Kerberos

To configure the JDriver to use Kerberos for SSO, additional modifications need to be made to the driver.properties file. The DSKerberosRealm and DSKerberosKDC properties need to be set to proper values. DSKerberosRealm should be set to the name of the Kerberos Realm. This value needs to be in uppercase. DSKerberosKDC should be set to the hostname of the server that is acting as the Kerberos Key Distribution Center. In configuration described above, the Kerberos KDC would be the Windows Active Directory server.

Documents

TIBCO GridServer?? Installation Guide€¦ · TIBCO GridServer® installs into a datasynapse directory within TIBCO_HOME. This directory is referenced in documentation as DS_INSTALL