open deploy admin strati on guide

OpenDeploy®

Administration Guide

Release 6.1

© 1997-2006 Interwoven, Inc. All rights reserved.

No part of this publication (hardcopy or electronic form) may be reproduced, translated into another language, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written consent of Interwoven. Information in this manual is furnished under license by Interwoven, Inc. and may only be used in accordance with the terms of the license agreement. If this software or documentation directs you to copy materials, you must first have permission from the copyright owner of the materials to avoid violating the law which could result in damages or other remedies.

Interwoven, TeamSite, Content Networks, OpenDeploy, MetaTagger, DataDeploy, DeskSite, iManage, LiveSite, MediaBin, MetaCode, MetaFinder, MetaSource, OpenTransform, Primera, TeamPortal, TeamXML, TeamXpress, VisualAnnotate, WorkKnowledge, WorkDocs, WorkPortal, WorkRoute, WorkTeam, the respective taglines, logos and service marks are trademarks of Interwoven, Inc., which may be registered in certain jurisdictions. All other trademarks are owned by their respective owners. Some or all of the information contained herein may be protected by patent numbers: US # 6,505,212, EP / ATRA / BELG / DENM / FINL / FRAN / GBRI / GREC / IREL / ITAL / LUXE / NETH / PORT / SPAI / SWED / SWIT # 1053523, US # 6,480,944, US# 5,845,270, US #5,384,867, US #5,430,812, US #5,754,704, US #5,347,600, AUS #735365, GB #GB2333619, US #5,845,067, US #6,675,299, US #5,835,037, AUS #632333, BEL #480941, BRAZ #PI9007504-8, CAN #2,062,965, DENM / EPC / FRAN / GRBI / ITAL / LUXE / NETH / SPAI / SWED / SWIT #480941, GERM #69020564.3, JAPA #2968582, NORW #301860, US #5,065,447, US #6,609,184, US #6,141,017, US #5,990,950, US #5,821,999, US #5,805,217, US #5,838,832, US #5,867,221, US #5,923,376, US #6,434,273, US #5,867,603, US #4,941,193, US #5,822,721, US #5,845,270, US #5,923,785, US #5,982,938, US #5,790,131, US #5,721,543, US #5,982,441, US #5,857,036, GERM #69902752.7or other patents pending application for Interwoven, Inc.

This Interwoven product utilizes third party components under the following copyright with all rights reserved: Copyright 1995-1999, The Apache Group (www.apache.org); Copyright 1986-1993, 1998, Thomas Williams, Colin Kelley. If you are interested in using these components for other purposes, contact the vendor.

Interwoven, Inc.803 11th Ave. Sunnyvale, CA 94089

http://www.interwoven.comPrinted in the United States of America

Release 6.1Part #90-21-00-610-300April 2006

Table of Contents

About This Book 13Notation Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Other OpenDeploy Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

OpenDeploy Installation Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Database Deployment for OpenDeploy Administration Guide . . . . . . . . . . . . . . . . . . 15OpenDeploy Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15OpenDeploy Release Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Online Help. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Chapter 1: Getting Started 17Starting OpenDeploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Starting the User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Stopping OpenDeploy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Running OpenDeploy as Non-Administrator or Non-Root. . . . . . . . . . . . . . . . . . . . . . . . . . . 24Running OpenDeploy on Windows as Non-Administrator . . . . . . . . . . . . . . . . . . . . . 24Running OpenDeploy on UNIX as Non-Root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Refreshing the OpenDeploy Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28OpenDeploy User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Browser Refresh Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Accessing the User Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Logging In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Timeout Setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

OpenDeploy Server Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Adding OpenDeploy Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Changing Server Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Deleting OpenDeploy Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Monitoring Server Logs and Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Server Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Managing Server Group Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Reconnecting to a Restarted OpenDeploy Server . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Determining the OpenDeploy Server Version. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Displaying the OpenDeploy Server Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Composing Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Using a Text or XML Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Using the Deployment Configuration Composer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Viewing Deployment Configuration Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Uploading Deployment Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Organizing Deployment Configurations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Creating Deployment Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Viewing Deployment Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Directory Permissions for Deployment Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Assigning Access Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

3

Running Deployments from the User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Starting a Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Performing a Test Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Performing a Simulated Deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Cancelling Deployments in Progress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Monitoring Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Viewing Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Deployments Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Details Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Source Deployments Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Target Deployments Window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Deployment Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Running Deployments from the Command Line. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Authorization Checking. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Starting a Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Performing a Simulated Deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Specifying a Deployment Instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Running Deployments Asynchronously . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Cancelling a Deployment in Progress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Roles and Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Administrator Role. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71User Role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Server Access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Deployment and Deployment Groups Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Authorizing Deployments and Deployment Groups from the Command-Line. . . . . . . . 76Role Access in TeamSite Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Chapter 2: Deployment Types 79Deployment Configuration Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Understanding the Configuration DTDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Encoding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Naming Deployment Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Deployment Configuration Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Specifying the Deployment Host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Specifying the Connection Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87Configuring Concurrency Management Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Target Replication Farms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Specifying the Replication Farm Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Configuring the Replication Farm within the Deployment Configuration . . . . . . . . . . . 90Referencing Target Replication Farms in the Nodes Configuration File . . . . . . . . . . . . 92Reverse Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Source File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Target File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97File Filters and Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Windows Path Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Deployment Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

4 OpenDeploy Administration Guide

Transactional . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Definition-Specific Configurations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Directory Comparison Deployments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Defining the Source File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Defining the Target File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Resolving Time Zone Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Deploying Files When Extended Attributes Change. . . . . . . . . . . . . . . . . . . . . . . . . 106

TeamSite Comparison Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Defining the Source TeamSite Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Defining the Target File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Deploying TeamSite Extended Attributes with TeamSite Files . . . . . . . . . . . . . . . . . . 113Comparing Files with Extended Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Writing Extended Attributes to a Manifest File. . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Use With Deploy and Run Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

File List Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116Defining the Source File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Editing the File List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Specifying the File List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Defining the Target File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119Using doDeletes with File List Deployments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Configuring TeamSite Source File Locations on UNIX Hosts . . . . . . . . . . . . . . . . . . . . . . . . 120Recommended Path Prefixes for Directory Comparison, File List or Payload Deployments120Recommended Path Prefix for TeamSite Comparison Deployments . . . . . . . . . . . . . . 121

Payload Adapter-Based Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Defining the Source File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Specifying the Target File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Specifying the Payload Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Providing Input to the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125OpenDeploy Query Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Deployment Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129Writing Payload Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129Metadata-Based Deployments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Data Asset Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135Database Auto-Synchronization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135Standalone Database Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136Target-Side Database Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Synchronized Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Defining Source-Based Overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140Defining Target-Based Overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Specifying Different Target Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141Defining Features on a Target-Specific Basis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Deployment Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142Using Example and Sample Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Example Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143Sample Configurations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Redeploying Legacy Web Sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

5

Chapter 3: Content Delivery Methods 145Transactional Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145Fan-Out Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

EasyDeploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147Transactional Targets in Fan-Out Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147Determining the Success Criteria (Quorum) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

Multi-Tiered Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149EasyDeploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152Transactional Targets in Multi-Tiered Deployments . . . . . . . . . . . . . . . . . . . . . . . . 152Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Routed Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156How Route Definitions Are Determined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Specifying End Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159Resolving Unspecified Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159File Manifest Determination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Transactional . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Manifest Information Stream Format Requirement . . . . . . . . . . . . . . . . . . . . . . . . . 162Configuring Route Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162Configuring Route Segments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163Specifying Next-Tier File Locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164Referencing the Route Definition in the Deployment Configuration . . . . . . . . . . . . . 166Specifying a Common Host for Simplified Checking . . . . . . . . . . . . . . . . . . . . . . . . 167Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Reverse Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Deployment Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

Certified Limits for Number of Deployment Legs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171Certification Factors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171Environmental Factors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172Examples and Recommendations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Chapter 4: Deployment Features 175Filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

Filter Placement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177Inclusion Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179Exclusion Filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181Exception Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182Combining Filter Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185Specifying Path Syntax for Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185Supported Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Comparison Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187Date-Based Comparison Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Transfer Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

Permission Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193Cross-Platform Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195User and Group Ownership Transferal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Setting the File Transport Buffer Size (Bandwidth Throttling) . . . . . . . . . . . . . . . . . . . . . . . 196Using OpenDeploy with ACLs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198


ACL Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198ACE Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198Ignoring and Preserving ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199Enabling UNIX-Based Deployments When Extended ACLs Are Present. . . . . . . . . . . 200

Deploying Symbolic Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201Parameter Substitution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

Default Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204Running Deployments with Parameter Substitution. . . . . . . . . . . . . . . . . . . . . . . . . 204Use with Deployment Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206Use with Scheduled Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206Use with Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206Parameter Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

Utilizing the Delivery Adapter Framework. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208How Delivery Adapters are Incorporated into Deployments . . . . . . . . . . . . . . . . . . . 209Configuring Delivery Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210Specifying Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211Writing Delivery Adapters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211JDK Requirement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212Sample Delivery Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

DataDeploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214Enabling DataDeploy on the Source Base Server . . . . . . . . . . . . . . . . . . . . . . . . . . . 214Database Deployment in the Deployment Configuration . . . . . . . . . . . . . . . . . . . . . 214

Chapter 5: Deploy and Run 215Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Interacting with the Windows Desktop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Deployment-Level Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217Task-Level Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227Specifying Allowed Deploy and Run Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229Ordering of Deploy and Run Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

Usage of the Deployment Information Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231Information Stream Output Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Disabling Deploy and Run Executions on the Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233Deploying to a Package File Using Deploy and Run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233Secure Invocation of External Applications on UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

Chapter 6: Scheduled Deployments 235Scheduling from the User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

Resolving Time Zone Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236Scheduling Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237Viewing Schedules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239Viewing Scheduled Deployment Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239Editing Scheduled Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240Deleting Scheduled Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241Activating and Deactivating Scheduled Deployments . . . . . . . . . . . . . . . . . . . . . . . . 241

Scheduling from the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

7

Adding a Schedule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242Viewing Scheduled Deployment Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245Deleting a Schedule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247Activating and Deactivating a Schedule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

Reactivating Schedules During or Past Their Effective Period. . . . . . . . . . . . . . . . . . . . . . . . 250

Chapter 7: Logging 251Log File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251Log File Permissions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251Viewing Log Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

Viewing Log Files from a Text Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252Viewing Log Files from the OpenDeploy User Interface . . . . . . . . . . . . . . . . . . . . . 252

Base Server Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254Receiver Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255Macro Deployment Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

Source Macro Deployment Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256Receiver Macro Deployment Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

Micro Deployment Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258Source Micro Deployment Log. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259Receiver Micro Deployment Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

Logging Levels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262Defining Logging Levels in the User Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262Defining Logging Levels from the Command Line. . . . . . . . . . . . . . . . . . . . . . . . . . 262

Logging Configuration Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263Base Server and Receiver Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263Deployment Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

Logging Rules Hierarchy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264Base Server and Receiver Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264Macro and Micro Deployment Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

Log File Size Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265Rollover Threshold Size Determination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266Rolled Over Log File Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

Log File Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267Base Server and Receiver Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267Deployment Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

Administration Server Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268Reporting Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268Adapter Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

Chapter 8: Reporting 271Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

Server Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272Server Reporting Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

Administration Server Configuration for Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276Connection Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277Sub-Process Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278


Reporting Server Database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280Upgrading Reporting Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291Upgrading the Default Reporting Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292Adding Servers to the Reporting Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294Using a Third-Party Database for Store-and Forward System . . . . . . . . . . . . . . . . . . 295

Custom Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297Configuring Custom Report Queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298Generating Custom Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300Downloading Custom Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304Saving Custom Reports as a Quick Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

DAS Custom Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305ControlHub Custom Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307SQL Query Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

SQL Report Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311Generating SQL Query Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312Downloading an SQL Query Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312Saving an SQL Query Report as a Quick Report . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

Quick Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313Adding New Entries to Quick Report List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314Editing Existing Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314Deleting Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

Managing Report Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315Reporting Database Sizing Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

Sending OpenDeploy Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316Receiving OpenDeploy Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316Database Auto-Synchronization (DAS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

Chapter 9: Encryption 317Symmetric Key Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

Configuring OpenDeploy for Symmetric Encryption . . . . . . . . . . . . . . . . . . . . . . . . 317Using Symmetric Encryption with Reverse Deployments . . . . . . . . . . . . . . . . . . . . . 318

Secure Data Transfer with SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319Obtaining Additional SSL Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319Setting Up for SSL Private Keys and Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . 319Setting Up the Certificate Authority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321Generating a Certificate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323Support for Third-Party Certificate Authority . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325Changing OpenSSL Defaults. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326SSL Configuration and Deployment Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326Verifying Certificates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327Using Multiple Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328Configuring OpenDeploy for SSL Data Transfer Encryption . . . . . . . . . . . . . . . . . . . 329Ciphers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330Testing the SSL Encryption Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333Support for Third-Party Certificate Authority When Using SSL Encryption . . . . . . . . 333

Chapter 10: Composing Deployments 335Deployment Configuration Composer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

9

Tree and Errors Tabs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337Details Pane. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338

Types of Deployment Configuration Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339Global Deployment Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339Definition Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340

Creating a New Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341Naming the Deployment Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342Specifying the Parameter Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342Specifying the Log Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342Verifying or Changing the Source Host Name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343Configuring the Concurrency Management Settings . . . . . . . . . . . . . . . . . . . . . . . . 344Specifying the Connection Timeout Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344Specifying Deployment Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344Specifying the File Transport Buffer Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346Naming the Replication Farm Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347Adding Target Host Nodes to the Replication Farm Element . . . . . . . . . . . . . . . . . . 347Assigning Next-Tier Deployments to Target Hosts . . . . . . . . . . . . . . . . . . . . . . . . . 348Specifying a Transactional Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349Setting Deploy and Run. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349Specifying a Routed Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356Naming and Adding Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357Selecting the Definition Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357Defining the Source File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358Defining a Subdirectory Within the Source File Location . . . . . . . . . . . . . . . . . . . . . 361Configuring Payload Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362Applying Source-Side Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366Following Source-Side Symbolic Links in Deployments . . . . . . . . . . . . . . . . . . . . . . 371Designating Alternate Targets from the Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372Defining the Target File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373Specifying the Target Replication Farm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375Applying Comparison Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375Applying Transfer Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376Applying Permission Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378Configuring for Use with Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381Applying Target-Side Filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381Saving the Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382

Editing Deployment Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383Editing Configuration From Previous OpenDeploy Releases. . . . . . . . . . . . . . . . . . . 383

Creating DataDeploy Wrapper Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384Editing Remote Upgrade Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385

Configuring Remote Action Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386Configuring Target Progress Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387Initial Polling Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388

Chapter 11: Syndication 389How Syndication Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390

Offers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390Schedules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391


User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391Offers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391Configuring Payload Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400Schedules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406Suspending Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407Viewing Subscriptions from the Offer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407

Command-Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408Offers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410Specifying the Deployment Schedule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416Processing the Subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420Displaying Offers and Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422Deleting Offers and Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423Suspending Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423Activating Suspended Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424Schedule Modifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425

Using Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426

Chapter 12: Web Services 427Using Web Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428OpenDeploy Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429Access Server Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429Tools and Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429

Chapter 13: Archival Module 431Archiving with Standalone OpenDeploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431Archiving with ControlHub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432

Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432Configuring Archival with ControlHub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432

Running Archival Module Tasks from the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . 437

Appendix A: Delivery Adapters 439Generic Delivery Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439

Adapter Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440Deployment Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440

FTP Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441Adapter Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441Deployment Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442

Email Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442Adapter Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443Deployment Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443

Network Appliance NetCache Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444Adapter Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445Deployment Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446Retrying When Push Fails But Overall Deployment Succeeds . . . . . . . . . . . . . . . . . . 446Internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447

BEA WebLogic 8 Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448Adapter Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448Deployment Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450

11

Use of “Upload” Directory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450BEA WebLogic 9 Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451

Adapter Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451Deployment Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451

IBM WebSphere Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453Adapter Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453Deployment Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457

BEA Bulk Loader Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458Adapter Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458Deployment Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460

Microsoft Application Center Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460Adapter Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460Deployment Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463

Microsoft COM+ Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464Adapter Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464Deployment Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467

Microsoft Global Assembly Cache (GAC) Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468Adapter Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468Deployment Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469

SunCIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470

Appendix B: Payload Adapters 471JDK Requirement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471Sample Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471File List Differential Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472

Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472Editing the File List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473

Database Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474Software Configuration Management Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475

IBM Rational ClearCase Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475Microsoft Visual SourceSafe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478Serena (Merant) PVCS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482Concurrent Versions System (CVS). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485MKS Source Integrity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487

IBM WebSphere Portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490

Glossary 493

Index 501


About This Book

OpenDeploy Administration Guide is a guide to install, configure, and use OpenDeploy ®. It is primarily intended for webmasters, system administrators, and those involved in deploying content between development servers and production servers.

If you are using OpenDeploy in conjunction with TeamSite®, you should also know TeamSite functionality and terminology. Many of the operations described in this manual require root or Administrator access to the OpenDeploy server host. If you do not have root or Administrator access to the OpenDeploy server host, consult your system administrator.

This manual uses the term “Windows” to indicate any supported version of the Microsoft Windows operating system, such as Windows NT® or Windows® 2000.

This manual uses the term “UNIX” to indicate any supported flavor of the UNIX® operating system.

Windows: Users should be familiar with either IIS or Netscape® Web servers, and with basic Windows server operations such as adding users and modifying Access Control Lists (ACLs).

UNIX: Users of this manual should be familiar with basic UNIX commands and be able to use an editor such as emacs or vi.

It is also helpful to be familiar with regular expression syntax. If you are not familiar with regular expressions, consult a reference manual such as Mastering Regular Expressions by Jeffrey Friedl.

13

Notation Conventions

This manual uses the following notation conventions:

Convention Definition and Usage

Bold Text that appears in a GUI element (for example, a menu item, button, or element of a dialog box) and command names are shown in bold. For example:

Click Edit File in the Button Bar.

Italic Book titles appear in italics. Terms are italicized the first time they are introduced.Important information may be italicized for emphasis.

Monospace Commands, command-line output, and file names are in monospace type. For example:

The iwodstart command-line tool starts an OpenDeploy deployment task.

Monospaced italic

Monospaced italics are used for command-line variables.For example:

iwodstart deployment

This means that you must replace deployment with your values.Monospaced bold Monospaced bold represents information you enter in response to

system prompts. The character that appears before a line of user input represents the command prompt, and should not be typed. For example:

iwodstart

Monospaced bold italic

Monospaced bold italic text is used to indicate a variable in user input. For example:

iwodstart deployment

means that you must insert the values of deployment when you enter this command.

[] Square brackets surrounding a command-line argument mean that the argument is optional.

| Vertical bars separating command-line arguments mean that only one of the arguments can be used.


Other OpenDeploy Documentation

Other OpenDeploy Documentation

In addition to this Administration Guide, OpenDeploy includes the following documentation components:

OpenDeploy Installation Guide

Database Deployment for OpenDeploy Administration Guide

OpenDeploy Reference

OpenDeploy Release Notes

Online help

OpenDeploy Installation Guide

OpenDeploy Installation Guide is a manual that contains installation, and server and host configuration information for OpenDeploy.

Database Deployment for OpenDeploy Administration Guide

Database Deployment for OpenDeploy Administration Guide is a guide for configuring OpenDeploy to deploy structured content to a database within the OpenDeploy environment. Certain database deployment tasks require the licensing of the DataDeploy module.

OpenDeploy Reference

OpenDeploy Reference is a manual that contains reference material on topics such as configuration DTDs, command-line tools (CLTs) and ports. Use this manual to find information on a specific reference topic quickly and easily.

OpenDeploy Release Notes

OpenDeploy Release Notes contains supplemental and late-breaking information regarding OpenDeploy not found in the other documentation. Refer to the OpenDeploy Release Notes for information regarding supported platforms, installation requirements, new features and enhancements, and known issues.

Online Help

OpenDeploy includes online help topics associated with each window in the OpenDeploy user interface. You can access the associated help topic by clicking the Help link in the upper right-hand corner of the window. The help topic will appear in a separate browser window that you can move and resize. You can display a navigation panel that provides you access to all the help topics by clicking the Show Navpane button. This panel provides you the ability to access help topics through the contents, index, and by using keyword searching.

15

Chapter 1

Getting Started

This chapter introduces the basic features and functions of OpenDeploy that you can perform from the user interface and command line. For some users, this information is sufficient to meet their OpenDeploy needs. For others, particularly those who want to create more complex deployment configurations, this chapter will provide the foundation upon which they can go on to the more advanced features described later in this book.

Starting OpenDeploy

OpenDeploy is run by starting its services or daemons. These services or daemons should be started in the following order:

Base server or receiver

Administration server

SNMP server

The method of starting these service and daemons differs depending on the type of platform on which it is operating.

Windows

Start OpenDeploy services on a Windows server by using one of the following methods:

Rebooting

Starting the OpenDeploy services from the Services window

Starting from the command line

Starting by Rebooting

After the OpenDeploy software is successfully installed on the server, the OpenDeploy services will automatically start upon rebooting. Be sure to have your bootstrap administrator already configured before rebooting. Refer to “Configuring the Bootstrap Administrator” on page 79 in the OpenDeploy Installation Guide for more information.

17

Getting Started

Starting from the Services Window

You can start OpenDeploy services from the Services window. You might prefer this method if the OpenDeploy services were previously stopped and it is impractical to restart the server.

OpenDeploy services can vary depending on what software components you have installed. Here is a table of OpenDeploy services and their corresponding software components:

To start the OpenDeploy services, follow these steps:

1. Open the Services window. This process may differ depending on which version of Windows you are using.

2. Right-click on Interwoven OpenDeploy 60 Service and select Start from the pop-up menu.

3. Right-click on Interwoven OpenDeploy UI Admin and select Start from the pop-up menu.

4. (optional) Right-click on Interwoven OpenDeploy 60 SNMP Service and select Start from the pop-up menu.

The optional OpenDeploy SNMP service allows you to monitor the status of an OpenDeploy server using an SNMP-enabled network management tool. Refer to “SNMP” on page 109 in the OpenDeploy Installation Guide for more information on this feature.

The services listed in the previous table, and in the steps to start OpenDeploy, represent the initial instance of OpenDeploy. If you have multiple instances of OpenDeploy running, those instances also are represented in the Services window. For example, if you had the instance marketing running, the Services window would appear as the following:

If you want to start a service associated with a particular instance, right-click on that instance’s service and select Start from the pop-up menu.

Service Software

Interwoven OpenDeploy 60 Service OpenDeploy base server or receiver

Interwoven OpenDeploy UI Admin Administration server

Interwoven OpenDeploy 60 SNMP Service SNMP server

Service

Interwoven OpenDeploy 60 Service

Interwoven OpenDeploy 60 Service: marketing

Interwoven OpenDeploy UI Admin

Interwoven OpenDeploy 60 SNMP Service

Interwoven OpenDeploy 60 SNMP Service: marketing


Starting OpenDeploy

Starting From the Command Line

To start one or more OpenDeploy services from the Windows command line, follow these steps:

1. Open a command line window and enter the following command to start the OpenDeploy service:

net start iwod60

2. Enter the following command to start the OpenDeploy UI Admin service:

net start iwodadmin

3. Enter the following command to start the SNMP service:

net start iwodsnmp60

When you create additional instances of your OpenDeploy base server or receiver, the instance name is appended to the iwod60 and iwodsnmp60 commands. For example, if you wanted to start an OpenDeploy or SNMP daemon associated with the server instance marketing, the start commands for the servers would be:

net start iwod60marketing and

net start iwodsnmp60marketing

UNIX

Start OpenDeploy daemons on a UNIX server by using one of the following methods:

Rebooting the server — After OpenDeploy software is successfully installed, OpenDeploy daemons will automatically start upon rebooting the server. Be sure to have your bootstrap administrator already configured before rebooting after installing your OpenDeploy software. Refer to “Configuring the Bootstrap Administrator” on page 79 in the OpenDeploy Installation Guide for more information.

Entering the start command at the prompt — In some cases it is not practical to shut down the server to start the OpenDeploy daemons. You can start OpenDeploy without rebooting the server by navigating to the location of the OpenDeploy start program.

19

Getting Started

Navigating to the init.d Directory

Starting the OpenDeploy daemons on a UNIX host requires navigating to the init.d directory. However, that directory resides in a different path depending on the platform. On some UNIX systems this will be od-home/etc/init.d or /etc/init.d. On others it will be od-home/etc/rc.d/init.d or /etc/rc.d/init.d.

Starting the Servers

To start the base server or receiver software, follow these steps:

1. Navigate to the appropriate init.d directory. See “Navigating to the init.d Directory” on page 20 for more information.

2. Start the OpenDeploy base server or receiver software by entering the following com-mand at the prompt:

./iwod60 start

3. Start the administration server by entering the following command at the prompt:

./iwodadmin start

4. (optional) Start the OpenDeploy SNMP software by entering the following command at the prompt:

./iwodsnmp60 start

The optional OpenDeploy SNMP service allows you to monitor the status of an OpenDeploy server using an SNMP-enabled network management tool. Refer to “SNMP” on page 109 in the OpenDeploy Installation Guide for more information on this feature.

When you create additional instances of your OpenDeploy base server or receiver, the instance name is appended to the iwod60 and iwodsnmp60 commands. For example, if you wanted to start an OpenDeploy or SNMP daemon associated with the server instance marketing, the start commands for the servers would be:

./iwod60marketing start and

./iwodsnmp60marketing start

Note that the TeamSite command-line tool iwreset does not restart OpenDeploy.

Starting the User Interface

Starting OpenDeploy does not automatically start the OpenDeploy user interface. After you have OpenDeploy running, you can access the user interface using a supported Web browser. See “OpenDeploy User Interface” on page 29 for more information.


Stopping OpenDeploy

Stopping OpenDeploy

OpenDeploy is stopped by terminating its services or daemons. These services or daemons should be stopped in the following order:

SNMP server

Administration server


The method of starting these service and daemons differs depending on the type of platform on which it is operating.

Windows

You must stop the various OpenDeploy services running on your Windows server to stop OpenDeploy.

Stopping from the Services Window

The following services correspond to the OpenDeploy software components:

To stop the OpenDeploy services from the Services window, follow these steps:


2. Right-click on Interwoven OpenDeploy 60 SNMP Service and select Stop from the pop-up menu to stop the SNMP server.

3. Right-click on Interwoven OpenDeploy UI Admin and select Stop from the pop-up menu to stop the administration server.

4. Right-click on the Interwoven OpenDeploy 60 Service and select Stop from the pop-up menu to stop the base server or receiver software.

Service Software

Interwoven OpenDeploy 60 SNMP SNMP server

Interwoven OpenDeploy UI Admin Administration server

Interwoven OpenDeploy 60 Service OpenDeploy base server or receiver

21

Getting Started

The services listed in the previous table, and in the steps to stop OpenDeploy, represent the initial instance of OpenDeploy. If you have multiple instances of OpenDeploy running, those instances are represented in the Services window. For example, if you had the instance marketing running, the Services window would appear as the following:

If you wanted to stop a service associated with a particular instance, right-click on that instance’s service and select Stop from the pop-up menu.

Stopping From the Command Line

To stop one or more OpenDeploy services from the Windows command line, follow these steps:

1. Open a command line window and enter the following command to start the SNMP service:

net stop iwodsnmp60

2. Enter the following command to start the OpenDeploy UI Admin service:

net stop iwodadmin

3. Enter the following command to start the OpenDeploy service:

net stop iwod60

If you wanted to stop an OpenDeploy server or SNMP service associated with a particular instance (for example, marketing), you would include the instance’s name in the command, for example:

net stop iwod60marketing and

net stop iwodsnmp60marketing

Service

Interwoven OpenDeploy 60 Service

Interwoven OpenDeploy 60 Service: marketing

Interwoven OpenDeploy UI Admin

Interwoven OpenDeploy 60 SNMP Service

Interwoven OpenDeploy 60 SNMP Service: marketing


Stopping OpenDeploy

UNIX

To stop the OpenDeploy daemons on a UNIX server, follow these steps:

1. Navigate to the appropriate init.d directory. See “Navigating to the init.d Directory” on page 20 for more information.

2. Stop the SNMP server by entering the following command at the prompt:

./iwod60snmp stop

3. Stop the administration server by entering the following command at the prompt:

./iwodadmin stop

4. Stop the base server or receiver software by entering the following command at the prompt:

./iwod60 stop

If you wanted to stop an OpenDeploy server or SNMP daemon associated with a particular instance (for example, marketing), you would include the instance’s name in the command, for example:

./iwodsnmp60marketing stop and

./iwod60marketing stop

23

Getting Started

Running OpenDeploy as Non-Administrator or Non-Root

You can configure OpenDeploy to run as someone other than the Administrator user on Windows or the root user on UNIX. The method differs depending on whether OpenDeploy is running on Windows or UNIX.

Running OpenDeploy on Windows as Non-Administrator

You can run OpenDeploy on Windows as non-Administrator by reconfiguring the Windows settings.

To run OpenDeploy on Windows as non-Administrator, follow these steps:

1. Open the Services window. This process may differ depending on the version of Windows you are using.

2. Stop the Interwoven OpenDeploy Service in the Services window.

See “Stopping OpenDeploy” on page 21 for more information on stopping OpenDeploy services.

3. Perform the following task depending on which Windows operating system you are using:

Windows 2000: select Action > Properties to open the Properties window. You must select any item in the Name column of the Services window for this command to be available. Next, select the Log On tab to make it active.

Windows NT: click Startup to open the Service window.

4. Click This account and enter the account user and password information in the appro-priate boxes.

5. Click OK and close the Services window.

6. Restart the OpenDeploy service you had previously stopped. See “Starting OpenDe-ploy” on page 17 for more information.

Running OpenDeploy on UNIX as Non-Root

You can convert an OpenDeploy base server or receiver running on UNIX to run as non-root by performing the following tasks:

Using the iwodnonroot command-line tool to change the user and group permissions of the files under the od-home directory to a non-root ownership.

Configuring OpenDeploy to start as a specified non-root user.

The following sections describe each of these tasks.



Changing Permissions to a Non-Root Ownership

The iwodnonroot command changes the ownership on the required OpenDeploy directories and files from root to a specified user and group ID. When OpenDeploy is run as that user and group ID, it can write and access the necessary files. You must be root to install OpenDeploy, and subsequently to run the iwodnonroot command.

Here is a listing of the iwodnonroot usage syntax:

iwodnonroot owner group [od-home]

-h Displays help information.

owner User name or ID

group Group name or ID

od-home Full path to the OpenDeploy home directory.

If the optional od-home argument is not specified, iwodnonroot will lookup the od-home from the following file:

/etc/defaultiwod60home

If od-home is specified, iwodnonroot will apply the chown/chgrp changes to the specified od-home location.

To prepare OpenDeploy on UNIX to run as non-root, follow these steps:

1. Stop the OpenDeploy base server or receiver daemon.

See “Stopping OpenDeploy” on page 21 for more information on stopping OpenDeploy daemons.

2. Navigate to the following directory:

od-home/bin

3. Start the conversion by entering the following command at the prompt:

iwodnonroot owner group

For example, if you wanted to convert OpenDeploy to run under the user ID jdoe and group ID tech_pubs, you would enter:

iwodnonroot jdoe tech_pubs

If you wanted to include the od-home location, the command might be:

iwodnonroot jdoe tech_pubs /usr/local/OpenDeployNG

4. Restart, as the user you specified using iwodnonroot, the OpenDeploy daemon you had previously stopped. See “Starting OpenDeploy” on page 17 for more information on starting OpenDeploy daemons.

25

Getting Started

Automatically Starting OpenDeploy as a Non-Root User

The OpenDeploy start-up script must be configured to automatically start as the non-root user you specified when running the iwodnonroot command. You must have already completed the steps listed in “Changing Permissions to a Non-Root Ownership” on page 25 before continuing on to this procedure.

You must be root to perform the following procedure.

The procedure for configuring the OpenDeploy start-up script can vary depending on the operating system. The procedure for Solaris is described here. If you are using another UNIX operating system, use these instructions as a starting point in conjunction with your operating system documentation.

To automatically start OpenDeploy as a non-root user on a Solaris host, follow these steps:


/etc/init.d

2. Create the symbolic link iwod_boot by entering the following command at the prompt:

ln -s /etc/init.d/iwod60 iwod60_boot

3. Create the file /etc/init.d/iwod60_boot_wrap using your favorite text editor, and include the following lines:

#!/usr/bin/csh# Wrapper script to start/stop OpenDeploy as non-root_user at boot

timesu - non-root_user -c "/etc/init.d/iwod60_boot $1"

where non-root_user is an alternate user name, for example odadm1.

4. Change the permission by entering the following command at the prompt:

chmod 775 /etc/init.d/iwod60_boot_wrap


/etc/rc3.d

6. Update the symbolic link S80iw0d60 by entering the following commands at the prompt:

rm S80iwod60

ln -s /etc/init.d/iwod60_boot_wrap S80iwod60


/etc/rc2.d

8. Update the symbolic link K80iwod60 by entering the following commands at the prompt:

rm K80iwod60

ln -s /etc/init.d/iwod60_boot_wrap K80iwod60



After completing this procedure, OpenDeploy will start up at boot time using the script iwod_boot. The iwod_boot script behaves like the S80iwod script and can detect when the booting up occurs. The script automatically cleans up OpenDeploy before starting if necessary.This allows for a clean and trouble-free startup, even if the previous shut down was not performed properly.

For starting and stopping OpenDeploy after you have booted, use the following script:

/etc/init.d/iwod60

rather than the script:

/etc/init.d/iwod60_boot_wrap

The iwod60 script can detect error situations such as starting OpenDeploy when it is already running, and when OpenDeploy has not been shut down properly.

Restrictions When Running as Non-Root

The following tasks can not be completed when running OpenDeploy as non-root on a UNIX host because these tasks typically require root authority:

Using file permission rules to impose user and group permissions on deployed content.

Replication of the source-side deployed content's owner and group.

Running Deploy and Run scripts as another user.

Accessing source content not readable by the running non-root OpenDeploy process.

Deploying to a target directory associated with someone other than the OpenDeploy process owner.

If you specify the following values for the permissionRules element’s attributes in the deployment configuration:

user="_iwod_user_" andgroup="_iwod_group_"

Note: "_iwod_user_" and "_iwod_group_" are literal values, not variables.

OpenDeploy skips the set ownership operations, which causes the deployed items to take on the ownership of the running OpenDeploy process. Refer to “Enabling UNIX-Based Deployments When Extended ACLs Are Present” on page 196 in the OpenDeploy Administration Guide for more information.

Note: These restrictions apply when running OpenDeploy as non-root on a UNIX host. Running OpenDeploy as non-Administrator on Windows will have similar privilege restrictions, if the ACLs on content or target directories are not accessible by the running OpenDeploy service.

27

Getting Started

Refreshing the OpenDeploy Server

Any time you modify certain elements in the base server, receiver, or nodes configuration files, you must reset your OpenDeploy base server or receiver service or daemon to accept the changes. You can refresh your OpenDeploy server without rebooting or manually restarting individual services or daemons by using the iwodcmd serverreset command-line tool. The iwodcmd serverreset command-line tool refreshes the OpenDeploy server with the new settings specified in the updated configuration files. Using this tool, you can make changes to the server configuration file and have it be read without having to bring down your services or restart your host.

The iwodcmd serverreset command-line tool will not cause the configuration to be refreshed if there are deployments in progress at the time the command is run.

The following elements in the base server and receiver configuration files (by default odbase.xml and odrcvr.xml) can be refreshed using iwodcmd serverreset:

allowedHosts

allowedDirectories

logRules

The following elements and their attributes in base server and receiver configuration file are not refreshable:

localNode

initiatorProperties

listenerProperties

transportProperties

schedulerProperties

To make the server read and implement changes in these elements, you must restart your OpenDeploy services or daemons.

Refer to the OpenDeploy Reference for descriptions of these elements and their attributes.

To refresh your OpenDeploy server’s configurations, follow these steps:


od-home/bin

2. Reset the OpenDeploy services by entering the following command at the prompt:

iwodcmd [-odinst instName] serverreset


OpenDeploy User Interface

There are various options associated with the iwodcmd serverreset command-line tool. Here is a listing of these options, along with the usage syntax:

iwodcmd [-odinst instName] serverreset [-h | -v | -q]

-odinst instName Uses OpenDeploy instance instName.

-h Displays usage information.

-v Displays version information.

-q Disables messages generated when there are active deployments in progress at the time iwodcmd serverreset is run.

-listpathreg Displays the path registry. The output format is a list of path-uuid pairs enclosed in square brackets, as follows: [path1,associated-deployment-uuid][path2,associated-deployment-uuid]


The user interface enhances your ability to perform and monitor OpenDeploy tasks anywhere in the enterprise. All that is needed is a supported Web browser, which avoids the need to install additional client software on each computer from which you might want to administer the product. Refer to the OpenDeploy Release Notes for a list of supported browsers. You must also have the OpenDeploy administration server software installed and its service or daemon running.

The user interface is a tool to help you learn the product and start using OpenDeploy right away. You will also find the graphical monitoring and scheduling features an advantage in managing deployments. However, more advanced features and configurations will still require you to work directly with configuration files and command-line tools.

If you are starting OpenDeploy for the first time after installing it, you must follow the procedures for first time start-up and login. After you have configured your server to recognize specific servers and hosts, and have created the Administrator and User roles for individuals, you can follow the normal procedures for starting the OpenDeploy user interface.

Browser Refresh Requirements

To ensure that changes you make to OpenDeploy are reflected in the user interface, you should configure your Web browser to refresh a page each time it is visited.

29

Getting Started

Accessing the User Interface

To access the OpenDeploy user interface, point your browser to the following URL:

http://admin-server-hostname:admin-port-number/iw/opendeploy/login

where admin-server-hostname is the name of the host running the administration server software, and admin-port-number is the administration server port number you chose when you installed the administration server software. For example, if your administration server host was named andromeda and you entered the administration port number 8081, then the URL to access the user interface would be:

http://andromeda:8081/iw/opendeploy/login

If you access the user interface from the same server on which the administration server software is running, you can use “localhost” as the administration server in the URL.

Logging In

Starting the user interface displays the login window (Figure 1).

Figure 1: OpenDeploy Login Window

You must enter the following information in the login window:

User name box — enter your user name as it will be authenticated by the ContentServices Foundation access service. If you also need to specify a domain, include the domain using the following syntax domain\user. For example:

WORKGROUP\jdoe

Password box — enter the password associated with the user name you provided.

Host list — select the OpenDeploy base server or receiver that you want to access upon logging in. You must have an Administrator or User role (see below) on the server you select. See “Selecting the Host” on page 31 for additional information.



Role list — select either admin or user depending on what role you are authorized on the selected server. See “Roles and Authorization” on page 71 for more information. If you are logging in for the first time as the bootstrap administrator, see “First Time Login Using Bootstrap” on page 32.

When you complete the login window and click Login, the administration server authenticates your login information with the ContentServices Foundation (CSF) access service. This server contains user authentication information for your OpenDeploy environment. If the CSF access service successfully authenticates the user login, the administration server then contacts the OpenDeploy base server or receiver you selected at login. The administration server matches your login information with a corresponding od-admin or od-user role on the OpenDeploy server, or with the server’s bootstrap administrator. If a match is made, the login is successful.

Selecting the Host

When logging in, you must select an OpenDeploy base server or receiver that is already installed and running in the OpenDeploy environment. By default, the Host list in the login window contains the following entries:

The host name on which the administration server is installed.

The entry localhost, which maps to the same host as the one where the administration server resides.

If the administration server resides on a host where no other OpenDeploy servers are present, you can select either the host name or localhost from the Host list. If the administrator server resides on a host where no other OpenDeploy servers are present, then you must add the server to which you want to connect to the administration server’s odservers.cfg file. The odservers.cfg file resides in the following location:

admin-home/odadmin/config

Open the file using your favorite text editor, and add a node element entry within the nodeSet element for the OpenDeploy server. For example:

<nodeSet><node name="mars" host="mars.mycompany.com" port="9173" ...>

</nodeSet>

You must complete the following attributes in the node element you add:

name — the logical name of the OpenDeploy server. This is the name that will appear it the Host list in the Login window.

host — the resolvable host name or IP address of the host on which the OpenDeploy server resides.

port — the RMI registry port of the OpenDeploy server.

31

Getting Started

After you complete editing the odservers.cfg file, close the file and restart the administration server. Now you can select the OpenDeploy server you want from the Host list in the Login window. See “Starting OpenDeploy” on page 17 for information on starting OpenDeploy services and daemons.

After you gain access to the user interface, you can add additional OpenDeploy servers through the user interface. See “OpenDeploy Server Management” on page 33 for more information.

First Time Login Using Bootstrap

The first time an OpenDeploy base server or receiver is accessed using the browser-based user interface, either when OpenDeploy is first installed, or a new OpenDeploy instance is created, you must log in as the bootstrap administrator to gain full administration access. If you have not configured a bootstrap administrator yet, you must do so before you can log in. Refer to “Configuring the Bootstrap Administrator” on page 79 in the OpenDeploy Installation Guide for more information.

Select the Administrator role when logging in as the bootstrap administrator. You can only log in as the bootstrap administrator under the Administrator (admin) role. If you log in with a User (user) role, the login will be rejected.

Timeout Setting

OpenDeploy includes a timeout feature for the user interface. This timeout feature is a security measure to prevent unauthorized access to an OpenDeploy user interface window that has been idle past the timeout period. Users who attempt to perform any task through the user interface past the timeout period will have to log in again. The default timeout period is measured in milliseconds, with the default value being 86400000 (24 hours).

To change the timeout value of the OpenDeploy user interface, follow these steps:

1. Open the framework.properties file using your favorite text editor: This file resides in the following location:

admin-home/httpd/iwwebapps/opendeploy/WEB-INF/conf

2. Provide a value in milliseconds for the DeployAdmin.ASContextLifeTime attribute. For example:DeployAdmin.ASContextLifeTime=3600000

This is the amount of time the login session can be idle before a new login is required.

3. Save and close the file.

4. Restart your administration server service or daemon. See “Starting OpenDeploy” on page 17 for more information. The OpenDeploy user interface automatically will time-out when idle past the number of milliseconds you entered.


OpenDeploy Server Management


You can manage all the instances of your OpenDeploy servers (base servers and receivers) from a single browser running the OpenDeploy user interface. You can apply OpenDeploy features and functionality available through the user interface to any OpenDeploy server listed, assuming you have the proper access and permissions, and the OpenDeploy server is capable of performing the particular task. You must add each OpenDeploy server you want to manage into the OpenDeploy Servers window (Figure 2). You can also modify and delete existing servers from this window.

Figure 2: OpenDeploy Servers Window

Adding OpenDeploy Servers

To add an OpenDeploy server to your user interface, follow these steps:

1. Select Servers > View Servers to display the OpenDeploy Servers window (Figure 2). Here you can see which OpenDeploy servers are currently listed, including their resolvable host name or IP address, and RMI registry port number.

2. Click New Server to display the New Server window (Figure 3).

Figure 3: New Server Window

33

Getting Started

3. Input the following information regarding the new server you are adding into the new server template:

Name — the logical name you define for the server.

Address — the resolvable host name or IP address of the host on which the server resides.

Port — the port assigned to the RMI registry service.

4. Click Save to add the new server. The OpenDeploy Servers window reappears (Figure 4) with the added server.

Figure 4: OpenDeploy Servers Window with Added Server

Changing Server Information

You can change the name, IP address, and RMI registry service port for any OpenDeploy server listed in the OpenDeploy Servers window.

To change the information of a selected OpenDeploy server, follow these steps:

1. Select Servers > View Servers to display the OpenDeploy Servers window (Figure 2).

2. Click the Edit button that corresponds to the OpenDeploy server whose information you want to modify. The Edit Server window (Figure 5) appears.

Figure 5: Edit Server Window

3. Make your modifications as necessary and click Save. The OpenDeploy Servers window reappears, reflecting the changes you made to the server.



Deleting OpenDeploy Servers

You delete servers from the OpenDeploy user interface through the OpenDeploy Servers window. You are only deleting the listing of that server in the user interface, not deleting any OpenDeploy software from the actual server. You can add any server you have previously deleted at any time.

To delete a selected OpenDeploy server from the user interface, follow these steps:

1. Select Servers > View Servers to display the OpenDeploy Servers window (Figure 2).

2. Click the Delete button that corresponds to the OpenDeploy server that you want to delete from the user interface.

3. Click OK when prompted to confirm that you want to delete that selected server. The OpenDeploy Servers window is refreshed, no longer displaying the server you just deleted.

Monitoring Server Logs and Configurations

The Server Management window (Figure 6) provides a single location in the user interface where you can monitor and access the configuration and log files associated with a selected OpenDeploy server.

Figure 6: Server Management Window

35

Getting Started

Within the Server Management window you can perform the following server configuration and log file tasks:

View the OpenDeploy base server and receiver log files of the selected OpenDeploy server.

View the names of the configuration files currently in use by the selected OpenDeploy server.

Upload a configuration file that you created or modified locally to a selected OpenDeploy server.

Refresh the OpenDeploy server’s services and daemons to reread and implement changes in configuration.

Display the XML code of a configuration file located in the od-home/(od-instance)/etc directory of a selected server.

Viewing the Base Server and Receiver Log Files

You can access and view the base server and receiver log files from the Server Management window. Refer to the OpenDeploy Administration Guide for information on the contents of the base server and receiver log files.

To view the base server and receiver log files, follow these steps:

1. Select Servers > Manage Server to display the Server Management window.

2. Select the name of the OpenDeploy server whose base server or receiver log you want to view from the Selected Server list.

3. Click View Log. A separate browser window appears displaying the OpenDeploy Log Viewer window containing the base server or receiver log file of the server you chose.

Uploading Modified Server Configuration Files

The Server Management window provides you the ability to upload any of the following server configuration files:

Base server (by default odbase.xml)

Receiver (by default odrcvr.xml)

Nodes (by default odnodes.xml)

SNMP (odsnmp.xml)

Event reporting (eventReportingConfig.xml)

JMS (jmsConfig.xml)

Database (database.xml)

from your local computer into the od-home/(od-instance)/etc directory of the selected server. Any file you upload must be a valid XML file that follows its associated configuration DTD.



For example, if you wanted to add or modify the base server file of a particular OpenDeploy server, such as changing an allowed directory, you could create or make the appropriate changes to that file and upload it to that server. You must still use a text or XML editor to modify the configuration file. You cannot modify the file from the Server Management window, only copy it to the server. This feature is only available to individuals holding an Administrator role on the affected OpenDeploy server. See “Roles and Authorization” on page 71 for more information.

Any modified configuration file you upload must have the same file name as the one you intend to replace. Names of the configuration files currently in use by the selected OpenDeploy server are displayed in the In-use Config Files section of the Server Management window. You can also upload other files with the .xml extension, but the OpenDeploy server will not be able to read those files upon refreshing. Additional steps are required to substitute a differently named configuration file for one currently in use by an OpenDeploy server.

If you want to modify a configuration file currently in use by the selected OpenDeploy server, you are responsible for obtaining a copy of that file and placing it on your local host. You cannot download server configuration files through the OpenDeploy user interface. You will have to map a drive to the selected host or to find another method to copy the file you want from the selected server to your local host.

To upload a modified configuration file to a remote OpenDeploy server, follow these steps:

1. Create a new configuration file or modify an existing one on your local host.


3. Select the name of the OpenDeploy server to which you want to upload files from the Selected Server list.

4. Enter the path to the configuration file you want to upload to the selected server in the Upload File box (Figure 7). You can also click Browse and navigate to the location of the file. Any file you upload must have the .xml extension.

Figure 7: Uploading a Configuration File to a Remote OpenDeploy Server

5. Check the Overwrite box. This is required any time you are overwriting an existing configuration file.

6. Click Upload to copy the file you specified from your computer to the selected OpenDeploy server. Your file will be copied to the od-home/(od-instance)/etc directory, and will overwrite the existing file there.

37

Getting Started

The OpenDeploy server receiving your uploaded file will not run with the changes in the updated configuration file until you refresh the server. See “Refreshing the OpenDeploy Server” on page 38 for more information.

Viewing Server Configuration Files

You can view the XML source code of the configuration files, and other XML-based files that reside in the od-home/(od-instance)/etc directory of a selected OpenDeploy server, through the Server Management window. This is a quick and convenient way to see how a selected OpenDeploy server is configured. Only valid XML files will be displayed. Any other file will produce an error message, even if it appears in the View File list. This feature is only available to individuals holding an Administrator role on the selected OpenDeploy server. See “Roles and Authorization” on page 71 for more information.

To view the source code of an OpenDeploy server configuration file, follow these steps:


2. Select the name of the OpenDeploy server whose configuration file source code you want to view from the Selected Server list.

3. Select the file whose source code you want to view from the View File list. The source code is displayed in the Configuration window (Figure 8) immediately below the list.

Figure 8: View File List and Configuration Window

If a file you want to view does not appear in the View File list, ensure that the file resides in the od-home/(od-instance)/etc directory of the selected server. If you receive an error message after selecting a file, it may not be a properly formatted XML file.

Refreshing the OpenDeploy Server

Any changes you made to the configuration files in use will only be read and followed when you refresh that server. This applies both to changes you make to configuration files that you uploaded through the Server Management window, and to changes you make by modifying the configuration files directly on the server.

You can refresh the selected OpenDeploy server through the Server Management window. Refreshing the server causes it to reread its configuration files currently in use. These files are displayed in the Server Management window (Figure 6) under In-use Config Files.



The refresh feature in the Server Management window functions the same as the iwodcmd serverreset command-line tool. See “Refreshing the OpenDeploy Server” on page 28 for more information, including a list of those supported elements.

For example, if you modify the log file directory of the base server configuration file of a selected OpenDeploy server, the new log file directory will only be used after the server is refreshed. Any configuration change you make will only be applied to actions that occur after the server is refreshed. OpenDeploy will not retroactively apply changes, such as moving the older log files from their previous location to the new one you specified.

Refreshing OpenDeploy only applies to the configuration files whose names appear in the In-use Config Files section of the Server Management window.

You cannot change the name of configuration files in use by a selected server through the OpenDeploy user interface, nor can you select a different configuration file. Changing the configuration files can only be done by modifying the service configuration file (deploy.cfg) and restarting the OpenDeploy services or daemons. Refer to “Modifying the Service Configuration File” on page 74 in the OpenDeploy Installation Guide for more information about modifying the base server service and receiver service configuration files.

As the refresh on the selected server takes place, the progress is logged in the base server or receiver log file. Check these logs to determine when the refresh procedure has completed before resuming OpenDeploy tasks.

This feature is only available to individuals holding an Administrator role on the affected OpenDeploy server. See “Roles and Authorization” on page 71 for more information.

To refresh a selected OpenDeploy server’s configuration files, follow these steps:


2. Select the name of the OpenDeploy server whose configuration files you want to refresh from the Selected Server list.

3. Click Refresh Server to begin the refreshing procedure.

4. Click View Log to display a separate browser window containing the OpenDeploy Log Viewer window. Here you can view the base server or receiver log file to follow the progress of the refresh.

39

Getting Started

Server Groups

A server group is a collection of OpenDeploy servers on which you can perform the following tasks to all servers in a single action:

Update OpenDeploy servers’ configuration files (including overwriting existing files).

Refresh the servers to enable the configuration changes.

View the updating and refreshing status of a selected server group.

The configuration files you can update and apply are the same ones listed in “Uploading Modified Server Configuration Files” on page 36.

You can create any number of server groups. An OpenDeploy server can appear in more than one server group.

Creating a Server Group

You can create a server group from any number of the existing OpenDeploy servers managed in the browser-based user interface. If you want to include an OpenDeploy server in a server group, but it is not listed in the user interface, you must first add the server, then create the server group. You can also add a server to an existing server group.

To create a server group, follow these steps:

1. Select Servers > View Server Groups to display the OpenDeploy Server Groups window (Figure 9).

Figure 9: OpenDeploy Server Groups Window



2. Click New Server Group to display the New Server Group window (Figure 10).

Figure 10: New Server Group Window

3. Enter the name of the server group in the Node Group Name box.

4. Select an OpenDeploy server you want to include in the server group from the New Nodes to Add list and click Add.

Repeat this step for each server you want to add. If you want to remove a server from the Included Nodes list, select it and click Remove.

5. Click Save to save the server group you created. The updated OpenDeploy Server Groups window is displayed (Figure 11).


41

Getting Started

Viewing Server Groups

To view your server groups, select Servers > View Server Groups to display the OpenDeploy Server Groups window (Figure 12).


Each server group is displayed. You can view the servers associated with a server group by viewing its associated Servers list. From this window you can also edit or delete an existing group, or add a new one. These tasks are described elsewhere in this section.

Editing Server Groups

You can add or delete servers from an existing server group at any time.

To edit a server group, follow these steps:


2. Click the Edit button associated with the server group you want to modify. The Edit Server Group window is displayed(Figure 13).

Figure 13: Edit Server Group Window



3. Add or remove servers from the server group by selecting them and clicking the Add and Remove buttons are necessary.

When you perform another function, such as opening another window, you changes you made to the server group are automatically saved.

Deleting Server Groups

To delete a server group, follow these steps:


2. Click the Delete button associated with the server group listed that you want to delete. The OpenDeploy Server Groups window is automatically refreshed with the deleted server group no longer displayed.

Managing Server Group Configuration Files

You can modify a single base server or receiver configuration file and apply it to all the OpenDeploy servers associated with a server group. You cannot have a server group that contains a mix of base server and receivers to perform this task, so you must consider that when creating your server groups.

The following section describes creating and uploading server configuration files to a server group.

Editing Configuration Files for Server Groups

Server configuration files intended for server groups can be created and edited in the same manner as those for a single server. However, in some cases host addresses in the configuration files must be customized for that target server, such as the localNode element’s host attribute value in the base server or receiver configuration file. Another example would be in the nodes configuration file, where you might want to include a node entry for the sending server to allow it to send deployments to itself for testing purposes.

To accommodate this requirement, you must include the parameter $hostname for the affected attribute values. When the configuration file is uploaded, OpenDeploy automatically substitutes the host address associated with the server in the browser-based user interface. For example, if the OpenDeploy server mars had a host address of 114.342.23.20, then when the configuration file is uploaded, OpenDeploy would substitute that address value for the $hostname value. You can view the associated host address for each server in the OpenDeploy Servers window. See “OpenDeploy Server Management” on page 33 for more information.

43

Getting Started

OpenDeploy substitutes whatever address value is associated with the affected server in the browser-based user interface. This address can be an IP address or a resolvable host name, and you can include a mix of both types in a server group. See “Adding OpenDeploy Servers” on page 33 for more information on adding servers to the user interface.

In the following example, the server group western region contains the following servers and their associated addresses:

mars — 114.342.23.20

saturn — saturn

venus — venus.mycompany.com

If you wanted to update their base server configuration files, you would need to include the $hostname parameter for the localNode element’s host attribute value in the file you intend to upload:

<localNode host="$hostname"/>

When uploading the file to the target servers, OpenDeploy substitutes the host address associated with each server, so that the localNode element in the base server configuration file for each target server would now be:

mars — <localNode host="114.342.23.20"/>

saturn — <localNode host="saturn"/>

venus — <localNode host="venus.mycompany.com"/>

Uploading Modified Configuration Files to the Server Group

Uploading modified configuration files to a server group is the basically same as for a single servers. When you upload the files, they are applied equally to all the servers in the server group. See “Uploading Modified Server Configuration Files” on page 36 for a general discussion of how uploading modified configuration files remotely works.

In cases where a value in the configuration file being uploaded needs to reflect the particular host on which the target server resides, you must edit the configuration file using the $hostname parameter as appropriate. See “Editing Configuration Files for Server Groups” on page 43 for more information.

To upload modified configuration files to a server group, follow these steps:

1. Create a new configuration file or modify an existing one on your local host.



2. Select Servers > Manage Server Groups to display the Server Group Management window (Figure 14).

Figure 14: Server Group Management Window

3. Select the server group to which the uploaded configuration file will be applied from the Selected Server Group list.

4. Enter the path to the configuration file you want to upload to the selected servers in the Upload File box (Figure 15). You can also click Browse and navigate to the location of the file. Any file you upload must have the .xml extension.

Figure 15: Uploading a Configuration File to a Server Group

5. Check the Overwrite box. This is required any time you are overwriting an existing file.

45

Getting Started

6. Click Upload to copy the file you specified from your host to the selected server group. Your file will be copied to the od-home/(od-instance)/etc directory of each server, and will overwrite the existing file there (if present).

The Server Group Status pane (Figure 16) displays the upload status:

Figure 16: Server Group Status Pane

If you did not check the Overwrite box (see step 5), any recipient servers that already have that file will not accept the new uploaded file, and the message Upload Failed will be displayed in the associated Status column for those servers.

Knowing your server group’s status is important, as you must wait for the current group task is complete, before you can start another one. Click Uploading/Refreshing Status to update the status of the upload if necessary.

The servers in the group receiving your uploaded file will not run with the changes in the updated configuration file until you refresh the them. See “Refreshing the Server Group” on page 46 for more information.

Refreshing the Server Group

Any changes you made to the configuration files for a server group in use will be implemented only after you refresh those servers. The same rules apply to updating a server group’s configuration files as when updating a single OpenDeploy server. See “Refreshing the OpenDeploy Server” on page 38 for more information.

To refresh a server group, follow these steps:

1. Select Servers > Manage Server Groups to display the Server Group Management window (Figure 14).

2. Select the server group you want to refresh from the Selected Server Group list.

3. Click Refresh Selected Server Group.



The Server Group Status table does not provide a continuous display. Instead, it polls the group’s servers each time you make a status check. If you are waiting for the upload to complete, you may need to check on the status several times until the completion notification is displayed.

To view the server group update status, follow these steps:

1. Select Servers > Manage Server Groups to display the Server Group Management window.

2. Click Get Selected Server Group Uploading/Refreshing Status.

The Server Group Status table in the Server Group Management window displays the upload status for each server in the group.

Reconnecting to a Restarted OpenDeploy Server

If you are accessing an OpenDeploy base server or receiver through the browser-based user interface, and that OpenDeploy server becomes unavailable, upon its restart you may re-access it by selecting an item from the navigation pane on the left side of the user interface. This action will refresh the user interface. You may have to select multiple times before access is finally reestablished.

Determining the OpenDeploy Server Version

You can determine which version of OpenDeploy you are running by using the iwodservergetversion command-line tool.

To determine the version of your OpenDeploy server, follow these steps:


od-home/bin

2. Display the version by entering the following command at the prompt:

iwodservergetversion

The -h option associated with the iwodservergetversion command-line tool will display help information.

iwodservergetversion -h


47

Getting Started

Displaying the OpenDeploy Server Status

You can display the status of the OpenDeploy server, including its registry port and the number of active deployments, by using the iwodcmd serverstatus command-line tool.

To display the status of your OpenDeploy server, follow these steps:


od-home/bin

2. Display the status by entering the following command at the prompt:

iwodcmd [-odinst instName] serverstatus

There are various options associated with the iwodcmd serverstatus command-line tool. Here is a listing of these options, along with the usage syntax:

iwodcmd [-odinst instName] serverstatus [-h | -v | -q]

-odinst instName Uses OpenDeploy instance instName.-h Displays help information.


-q Omits displaying the number of active deployments.


Composing Deployments


You can create a new deployment configuration file, or edit an existing one, using the following methods:

Using a text or XML Editor

Using the Deployment Configuration Composer

Using a Text or XML Editor

Because deployment configuration files are XML-based, you can use your favorite text or XML editor to open and modify any of them. Using a text or XML editor to edit configuration files requires you to have file system access to the OpenDeploy server where the deployment you want to create or modify resides.

All new and modified deployment configuration files must reside in the following location:

od-home/(od-instance)/conf

for OpenDeploy to use them. You can also organize subdirectories within the /conf location. See “Organizing Deployment Configurations” on page 53 for more information.

Modifying deployment configuration files requires an understanding of XML syntax, and of the deployment configuration DTD. You should not try to modify deployment configuration file unless you have expertise in both. See Chapter 2, “Deployment Types” for more information on modifying deployment configuration files.

Using the Deployment Configuration Composer

The Deployment Configuration Composer is a tool in the OpenDeploy user interface that allows you to create and modify existing deployment configurations without having to edit the files using a text or XML editor. Knowledge of XML is not required to use this tool. However, you do need to understand the OpenDeploy features and functionality described in Chapter 2, “Deployment Types” and Chapter 4, “Deployment Features” before you can create a complete deployment configuration. See Chapter 10, “Composing Deployments” for more information on how to use this tool.

49

Getting Started

Viewing Deployment Configuration Source Code

You can view the XML-based source code of a selected deployment configuration’s file (Figure 17) within the OpenDeploy user interface.

Figure 17: View Configuration Window

Viewing the source code of a deployment configuration allows you to identify and troubleshoot a deployment configuration file issue quickly. You can also use this feature simply to see what element and attribute values are present. However, you cannot actually edit a deployment configuration displayed in the Deployment Configuration window. Instead you must edit the deployment configuration either using a text or XML editor, or using the Deployment Configuration Composer. See “Composing Deployments” on page 49 for more information.


Viewing Deployment Configuration Source Code

To view the source code of a deployment configuration, follow these steps:

1. Select Configurations > View Configurations to display the Deployment Configuration window (Figure 18).

Figure 18: Deployment Configuration Window

2. Select the name of the OpenDeploy server containing the deployments whose configu-ration information you want to view from the Selected Server list.

3. Select the name of the deployment group in which the deployment configuration resides from the Deployment Group list.

If your configuration does not reside within a deployment group, but rather directly under the od-home/conf directory, select “/”. See “Organizing Deployment Configurations” on page 53 for more information on deployment groups.

4. Select the name of the deployment whose configuration information you want to view from the Deployment list. This information is displayed in the window below.

You can also view the configuration of a selected deployment in the Start Deployment window by clicking View Configuration.

51

Getting Started

Uploading Deployment Configurations

The required location for deployment configuration files is:


Deployment configuration files you place in this location will appear in the Start Deployment window’s Deployment list as a selectable deployment. You can run this deployment from the user interface or the command line, assuming that the deployment conforms to the XML syntax and deployment configuration DTD rules, and that individuals in the User role have the proper access.

You can upload deployment configurations through the Upload Configuration window (Figure 19).

Figure 19: Upload Configuration Window

Here you can upload a configuration from any accessible file system location into the od-home/(od-instance)/conf directory, including any deployment group subdirectories you have configured within the conf directory.

You must have Administrator role access to import deployment configurations in this manner. Individuals with User role access will be denied this feature. See “Roles and Authorization” on page 71 for more information.

To upload a deployment configuration, follow these steps:

1. Select Configurations > Upload Configuration to display the Upload Configuration window.

2. Select the name of the OpenDeploy server receiving the uploaded deployment configu-ration from the Selected Server list.


Organizing Deployment Configurations

3. Select the name of the deployment group into which you want to upload the deploy-ment configuration from the Deployment Group list.


4. Enter the path to the file you want to upload. You can also click Browse and navigate to the location of the file.

5. Check the Overwrite box if you are overwriting an existing deployment configuration file residing in the same location as the intended destination of the uploaded file.

6. Click Upload. The file you uploaded is now available for use.


You can organize your deployment configurations into deployment groups to simplify the management and authorization of deployments. This feature allows you to create a hierarchical organization of deployment configurations based your needs, such as the following:

Geographical region

Organization

Purpose

Additionally, you can assign different access to each group you create. This allows you to organize your deployments by role access. For example, if you created the deployment groups production and test, you could make each groups’ deployments only accessible to those who have the need. Some users could run production deployments, but not those in the test group.

You can further segment access by creating sub-groups within your deployment groups. Within the production group, you might want to have both internal and external groups, with access to each limited even further.

53

Getting Started

Creating Deployment Groups

Deployment configurations must reside in the following location:


Within this location, you can add subdirectories, known as deployment groups, to the /conf directory and organize your deployment configurations within them. For example:

od-home/conf/test/production/miscellaneous

You can have multiple layers of sub-groups within your deployment groups, for example:

od-home/conf/test/internalod-home/conf/test/external

Deployment groups are created using one of the following methods:

Creating subdirectories under the /conf directory of your OpenDeploy server.

Including a group subdirectory before the deployment name when editing a deployment configuration in the Deployment Configuration Composer. Use the “/” character as your separator. For example, if you were editing the deployment configuration refresh, you could append the new deployment group asia to the deployment in the Name box (Figure 20):

Figure 20: Appending a Deployment Group to the Deployment Name

When you click Save, OpenDeploy automatically creates the deployment group (if it did not already exist) and places the deployment configuration there. Your original deployment remains intact in its original location.



Viewing Deployment Groups

To view your deployment groups and the deployment configurations they contain, follow these steps:


Figure 21: View Configuration Window

2. Select the OpenDeploy server whose deployment groups and configurations you want to view from the Selected Server list.

3. Select the deployment group whose deployment configurations you want to view or edit from the Deployment Group list. If you want to view a deployment configuration that resides directly under the od-home/conf directory, select “/” (Figure 22).

Figure 22: Deployment Group List When Selecting Deployment Residing Directly Under /conf

4. Select the deployment configuration you want to view or edit from the Deployment list.

Only those deployment configurations residing under the deployment group you selected are displayed in the Deployment list.

Directory Permissions for Deployment Groups

On UNIX hosts, those deployment group directories created under the /conf directory should have “read-write-execute” permissions allowed for the user that the OpenDeploy base server process will be running as. For example, a permission of 755 will allow the deployment group subdirectory to be accessible and readable by all, but only full access to the OpenDeploy base server.

55

Getting Started

Assigning Access Controls

You can assign access controls to specific groups to limit who has access to deployments associated with that group. For example, you could restrict the ability of users to run deployments from the americas group to only those with the proper authorization. As new deployments are added to that group, only those with the proper group access can operate them. See “Deployment and Deployment Groups Access” on page 74 for more information.

Running Deployments from the User Interface

This section describes how start and cancel deployments using the browser-based user interface. For instructions on running deployments from the command-line, see “Running Deployments from the Command Line” on page 67.

An individual holding an Administrator role on the OpenDeploy server can start and cancel any deployment on that server. Individuals holding User roles on that server only can start and cancel deployments on that server that are assigned to them. Individuals holding either type of role can view the progress and status of any deployment.

Starting a Deployment

You should perform a test deployment using the test.xml deployment configuration before trying any other deployments. Performing the test will ensure that your OpenDeploy server is properly configured, and will give you practice with deployments. See “Performing a Test Deployment” on page 59 for more information.

You can start a deployment through the OpenDeploy user interface (Figure 23).

Figure 23: Start a Deployment Window



To start a deployment using the OpenDeploy user interface, follow these steps:

1. Select Deployments > Start Deployment to display the Start Deployment window.

2. Select the OpenDeploy server you want to act as the source of the deployment from the Selected Server list. When you select a particular server, its deployment choices become available in the Deployment list.

3. Select the deployment you want to start from the Deployment list. If you are perform-ing an initial test of OpenDeploy, select test.

4. Select your choice from one of the following Logging Level options:

Verbose — logs high level of detail on deployment events as they occur. This logging level is best suited for troubleshooting deployment problems or evaluating deployment performance. Verbose logging can create very large log files. This is the default logging level.

Normal — logs standard status and error messages. In most cases, this level of logging provides a sufficient amount of detail to meet your needs.

5. (Optional) Enter the instance name of the deployment in the Instance Name box. The use of instances is described later in this section.

6. (Optional) Enter the name=value pair for the parameter substitution in the Name=Value box. If you are adding multiple name=value pairs, separate each one with a comma (“,”). See “Parameter Substitution” on page 203 for more information on this feature.

7. Click Simulate Deployment if you want to perform a simulated deployment before actually moving files to the target servers. Otherwise, go on the next step. See “Per-forming a Simulated Deployment” on page 59 for more information.

8. Click Start Deployment to start the deployment. The Deployment Started window appears (Figure 24), displaying information regarding the deployment you just started.

Figure 24: Deployment Started Window

You can also start a deployment from the command prompt by invoking the iwodcmd start command-line tool. See “Starting a Deployment” on page 68 for more information.

57

Getting Started

Deployment Instance Naming

You can append the deployment name with a name, number, or some other identifying characters to create a unique instance of that deployment. This allows a deployment using the same configuration file to be run using a different deployment name. When you specify multiple instances of a deployments in this manner, they can run simultaneously. If instance name is not used, the deployment can only be run once, and a new running of the deployment cannot be started until the previous one has finished.

A common use of this feature is in situations where there are multiple users initiating the same deployment in an uncoordinated fashion (such as each running a workflow). By specifying a different instance for each running of the deployment, you can ensure all the deployment jobs get run.

You can specify an instance in the Instance Name box of the Start a Deployment window. The value you specify for the instance can be any combination of identifying characters. Spaces are not permitted in the instance name. Typically, instance names are numbers or a short descriptive term such as 01 or Monthly.

The deployment name and the instance name you specify are combined together to form the complete instance name. For example:

reports01 or

reportsMonthly

No delimiter character is included, although you can specify one as part of the instance name itself, such as a period (.) or underscore (_). This delimiter character appears in the complete instance name:

reports_01 or

reports.monthly

When you run or schedule a deployment with an instance, OpenDeploy appends the instance to the deployment name and uses that extended name in the browser-based user interface, logging, and anywhere else where the deployment is tracked or monitored.

You can also run deployments using instance naming from the command prompt using the iwodcmd start command-line tool and the -inst option. See “Specifying a Deployment Instance” on page 69 for more information.



Performing a Test Deployment

After you have installed and configured OpenDeploy, you should perform a test deployment to ensure everything is working correctly. The OpenDeploy software includes a test deployment configuration test.xml that will deploy files from one location to another on your OpenDeploy server. The test configuration only uses default settings present in the server configurations files, so no further configuration is required on your part.

When run, the test deployment configuration moves all the files residing in the directory:

od-home/(od-instance)/userlib

to the directory:

od-home/(od-instance)/tmp

Use either the OpenDeploy user interface or command-line method to start the deployment. See “Starting a Deployment” on page 56 for more information. If you successfully deployed the file to its designated target location on your server, then you are ready to perform a deployment to a target on another server.

Performing a Simulated Deployment

You can perform a simulated deployment of any deployment configuration using the Simulate Deploymentfeature. The Simulate Deployment feature performs a simulated deployment that does not actually transfer any content over to the target or trigger Deploy and Run scripts, but logs what would have been transferred over. Using this feature allows you to test out and see what would have been transferred if the deployment was actual. The record of this result is in the deployment log files.

To perform a simulated deployment, follow these steps:

1. Select Deployments > Start Deployment to display the Start Deployment window.

2. Select the OpenDeploy server you want to server the simulated deployment from the Selected Server list. When you select a particular server, its deployment choices become available in the Deployment list.

3. Select the deployment you want to simulate from the Deployment list.

4. Select your choice from one of the Logging Level options. This is the level of logging that will be performed for your simulated deployment. See “Starting a Deployment” on page 56 for more information.

5. Click Simulate Deployment to begin the simulation. The Deployment Started window appears.

6. Click View Details to display the View Deployments window. Here you can view deployment information for your simulated deployment just like an actual deployment.

59

Getting Started

7. Click View Log to view logging information. Here you can view the list of files that would have been included in an actual deployment.

After evaluating the simulated deployment, you can actually deploy the files to the target servers by clicking Start Deployment.

You can also perform a simulated deployment from the command prompt by invoking the iwodcmd start command-line tool with the -sim option. See “Performing a Simulated Deployment” on page 69 for more information.

Checking File Integrity on Production Servers

The Simulate Deployment feature can also serve as a valuable tool in ensuring the integrity of Web site files residing on your production servers. You can use this feature to determine if a targeted production server is out of sync with your development server. Running the Simulate Deployment feature will create an entry for any file that would be deployed in the deployment log file. A file that was deployed unexpectedly is indicative of a file being mistakenly or intentionally added, deleted, or changed. Use the Simulate Deployment feature regularly to ensure the integrity of your production server Web sites. See “Performing a Simulated Deployment” on page 59 for information on using the Simulate Deployment feature.

Cancelling Deployments in Progress

You can cancel a deployment in progress during certain stages of the deployment process depending on the type of deployment:

Initial setup — all deployments

Compare phase — deployments that compare files only

Transfer phase — all deployments

Pre-commit phase — transactional deployments only

The following sections describe each of these phases in greater detail.

Initial Setup

All deployments take time to set up the deployment before files are actually compared or moved. A larger deployment with more target servers take longer to perform its initial setup than a smaller deployment with a lower number of targets. Any deployment can be canceled during its setup phase.



Compare Phase

The compare phase is when OpenDeploy compares the files between file system locations or TeamSite areas. Those deployments that compare files can be canceled during their compare phases as well as their initial setup. The length of the compare phase is dependent on the number of files being compared. A small number of files in a deployment, even if their total file size is large, will result in a brief compare phase. A large number of files, even if the total file size is smaller, will result in a longer compare phase. Deployment types that do not compare files, such as file list deployments, do not have a compare phase.

Transfer Phase

All deployments contain a transfer phase, where the files are actually deployed to their targets. If you cancel a deployment during the transfer phase, OpenDeploy will complete the transfer of any file in progress, and then cease any further activity.

Pre-Commit Phase

Transactional deployments can be canceled before or during their pre-commit phase in addition to the other phases. The pre-commit phase is when OpenDeploy determines whether or not all the targets have successfully received their deployments.

Cancelling Deployments in the User Interface

The Details table in the Source Deployments window contains the Cancel Deployment button (Figure 25).

- Figure 25: Details Table with Cancel Deployment Button

This button is active when cancellation of a running deployment is permitted. If the deployment has progressed past that time, or if it is completed, the button is disabled. Clicking Cancel Deployment stops the deployment at that point. In some cases, the deployment cancellation window is too short to permit cancellation of the deployment. See “Monitoring Deployments” on page 63 for more information on the Details table.

A target server cannot cancel a deployment it is receiving.

You cannot restart a deployment after it has been cancelled. If a transactional deployment has been cancelled, the deployment is considered to have failed and is rolled back with the targets restored to their previous states.

61

Getting Started

Depending on the speed of the deployment phases and when you issue the cancellation order, it is possible that a deployment you attempt to cancel will be completed anyway. The time when a cancellation is possible might close before OpenDeploy can process the deployment cancellation order after you click Cancel Deployment. In other cases, the cancellation window can close before the user interface can fully display the Details table with the Cancel Deployment button displayed.

To cancel a deployment in progress sent by your server, follow these steps:

1. Select Deployments > View Deployments after a deployment has started to display the Source Deployments window.

If you started the deployment manually, you can click View Details in the Deployment Started window to display the Source Deployments window and the Details table for your deployment. Skip to step 4.

2. Select the OpenDeploy server whose deployment you want to cancel from the Selected Server list.

3. Select the link of the deployment you want to cancel. That deployment’s target servers are displayed in the Details table.

If the cancellation window for the deployment is still open, the Cancel Deployment button is displayed for that target.

4. Click Cancel Deployment to stop the deployment for each target server you want.

You can also cancel a deployment in progress from the command prompt by invoking the iwodcmd deploycancel command-line tool. See “Cancelling a Deployment in Progress” on page 70 for more information.


Monitoring Deployments


You can view information regarding the deployments being sent in the Source Deployments window (Figure 26) and received in the Target Deployments window. These windows include information on deployments that have already taken place, that are currently in progress, and that are pending. You can also access log information and other details on a specific deployment.

Figure 26: Source Deployments Window

To monitor the progress of your deployments, follow these steps:

1. Select Deployments > View Deployments to display the Source Deployments window.

2. Select the OpenDeploy server whose deployments you want to monitor from the Selected Server list.

3. Select one of the following choices from the View list:

Sending — select to display the Source Deployments window. Here information on deployments initiated by the server is displayed. See the following section for details on the contents of the Source Deployments window.

Receiving — select to display the Target Deployments windows. Here information on deployments received by the server is displayed. See the following section for details on the contents of the Target Deployments window.

63

Getting Started

Viewing Options

The viewing options are similar for both the Source Deployments and Target Deployments windows:

Active check box — check to view deployments that are currently active.

Completed check box — check to view deployments that have been completed. The number of deployments displayed can be modified. See “Completed Sent Deployments Limit” on page 66 and “Completed Received Deployments Limit” on page 67 for more information.

Pending check box (Source Deployments window only) — check to view scheduled deployments that have not occurred yet. You can specify the deployments pending to a specified number of days in the future by entering that number in the text box.

Update button — click to refresh the window after changing the viewing options.

Deployments Table

The Deployments table displays the following information regarding all deployments being sent or received by the selected server, depending on whether the Source and Target Deployments window is being displayed.

Name (ID) column — displays the name and identification number of the deployment. If an instance value was specified at the time the deployment was run or scheduled, the deployment name is appended with that instance. For example, if you ran the deployment reports and specified the instance value 01, that deployment would be displayed as reports01.

On the receiver, the name value is:

deployment.definition.target-server

where the following variables apply:

deployment — the name of the associated deployment.

definition — the name of the definition in the deployment configuration that contains the source/target pairing.

target-server — the logical name of the target server receiving a deployment as it appears in the nodes configuration file of the sending server.

Selecting a deployment name displays its details in the Details table.

Start column — displays the date and time the deployment started.

Target column (Source Deployments window only) — displays the name of each target server receiving the deployment.

Source column (Target Deployments screen only) — displays the name of the source server sending the deployment.

Status column — displays the current status of the deployment, such as whether it is running, pending, completed, or failed.

Elapsed column — displays the elapsed time the deployment has been running.

Owner column — displays the login name of the deployment's owner.



Details Table

Clicking the deployment name displays the Details table underneath the Deployments table (Figure 27).

Figure 27: Source Deployments Window — Details Table

The Details table displays information regarding the source server or target servers participating in the deployment you selected. If the Source Deployments window is displayed and you select a deployment with multiple target servers, each of those target servers will be displayed in the Details table.

Target Host (Source Deployments window only) — displays the name of the server receiving the deployment as it appears in the nodes configuration file of the sending server.

Source Host (Target Deployments window only) — displays the name of the server sending the deployment.

Progress column — displays the status and particular activity taking place regarding the deployment at that given time.

Elapsed column — displays the elapsed time the deployment has been running.

Average Data Rate column — displays the average data transmission rate of the deployment at that given time.

Type column— displays the type of deployment, such as directory comparison, TeamSite comparison, file list, and others.

Click Refresh to update the Details table with the latest information on the selected deployment, such as whether a deployment in progress has completed yet.

If you display the Source Deployments window while the deployment is in progress, the Details table will indicate the deployment is still in progress, and under certain circumstances gives you the option of cancelling the deployment. See “Cancelling Deployments in Progress” on page 60 for more information.

65

Getting Started

Source Deployments Window

The Source Deployments window (Figure 26) appears when you select Sending from the View list. The Source Deployments window contains information regarding deployments originating from the selected OpenDeploy server that are displayed in the Deployments table.

The deployment name and its ID are displayed in the Name (ID) column of the Deployments table, along with other information about the deployment. If an instance value was specified at the time the deployment was run or scheduled, the deployment name is appended with the instance value. See “Deployments Table” on page 64 for a description of the Deployments table contents.

Completed Sent Deployments Limit

By default, the Source Deployments window displays the last 50 deployment jobs completed (when the Completed option is selected) that were sent by the selected server. This number includes multiple instances of the same deployment configuration being run. You can adjust that number in the server’s base server configuration file. Refer to “Specifying the Completed Deployments List” on page 138 in the OpenDeploy Installation Guide for more information.

Target Deployments Window

The Target Deployments window (Figure 28) appears when you select Receiving from the View list.

Figure 28: Target Deployments Window

The Target Deployment window contains information regarding deployments being received by the selected OpenDeploy server. Like the Source Deployments window, selecting a deployment from the Name (ID) column displays additional information in the Details table underneath.


Running Deployments from the Command Line

Completed Received Deployments Limit

By default, the Target Deployments window displays the last 50 deployment jobs completed (when the Completed option is selected) that were received by the selected server. This number includes multiple instances of the same deployment configuration being run. You can adjust that number in the server’s base server or receiver configuration file. Refer to “Specifying the Completed Deployments List” on page 138 in the OpenDeploy Installation Guide for more information.

Deployment Logging

Clicking View Log for either a deployment listed in the Source Deployment window, or one of the deployment’s corresponding source or target server listings in the Details table will display various types of logging information. See Chapter 7, “Logging” on page 251 for more information.


Command-line tools only can be issued on the host console where the OpenDeploy server is installed.

You can start a deployment and perform associated tasks using the iwodcmd start command. There are various options associated with the iwodcmd start command-line tool. Here is a listing of these options, along with the usage syntax:

iwodcmd start -h | -v

iwodcmd start deployment [-async] [-inst instName] [-k "key=value"]+ [-sim] [-V (normal | verbose)]



deployment Name of the deployment to start.

-async Runs iwodcmd start command asynchronously. The iwodcmd start command will return before the deployment completes. See “Running Deployments Asynchronously” on page 70 for more information.

-inst instName Uses OpenDeploy instance instName.

67

Getting Started

-k "key=value" Key/value substitution with "key=value" as the arg value. See “Parameter Substitution” on page 203 for more information. Note that the parameter iwdd is reserved for performing a deployment of a DataDeploy configuration.

-sim Enables the simulated deployment feature. See “Performing a Simulated Deployment” on page 59 for more information.

-V arg Logging level with verbose or normal as args. See “Defining Logging Levels from the Command Line” on page 262 for more information.

The iwodcmd start command returns the following codes regarding the status of the deployment:

0 — succeeded

1 — failed to start

2 — ran and returned a failed status

9 — completed with errors

Authorization Checking

By default, authorization checking occurs anytime an individual attempts to run a deployment group or individual deployment. See “Roles and Authorization” on page 71 for more information.

You can disable the default authorization checking through the service configuration file (deploy.cfg). Refer to “Disabling Authorization Checking for Deployments Invoked Using iwodcmd start” on page 76 in the OpenDeploy Installation Guide for more information.

Starting a Deployment

To start a deployment from the command line, follow these steps:


od-home/bin

2. Start the deployment by entering the following command at the prompt:

iwodcmd [-odinst instName] start deployment

where deployment is the name of the deployment you want to start, and -odinst instName is the name of the specific OpenDeploy instance running the deployment (if necessary).

For example, if you wanted to run the deployment reports, you would enter the following command at the prompt:

iwodcmd start reports



Performing a Simulated Deployment

See “Performing a Simulated Deployment” on page 59 for a description of the simulated deployment feature and its application.

Performing a simulated deployment from the command-line requires adding the -sim option to the iwodcmd start command. For example, if you wanted to run the deployment reports as a simulated deployment, you would enter the following command at the prompt:

iwodcmd [-odinst instName] start reports -sim

Specifying a Deployment Instance

Deployments are appended using the iwodcmd start command with the -inst instance using the following syntax:

iwodcmd [-odinst instName] start deployment -inst instance

The value you specify for instance can be any combination of identifying characters. Spaces are not permitted in the instance name. Typically, instance names are numbers or a short descriptive term. For example:

iwodcmd start reports -inst 01 or

iwodcmd start reports -inst Monthly

The deployment name and the instance name you specify are combined together to form the complete instance name. For example:

reports01 or

reportsMonthly

No delimiter character is included, although you can specify one as part of the instance name itself, such as a period (.) or underscore (_). For example:

iwodcmd start reports -inst _01 or

iwodcmd start reports -inst .monthly

This delimiter character appears in the complete instance name:

reports_01 or

reports.monthly

See “Deployment Instance Naming” on page 58 for more information on this feature.

69

Getting Started

Use with Parameter Substitution

The deployment instance feature is often used with the parameter substitution, which allows you to run a single deployment while specifying different parameter values for each instance. See “Parameter Substitution” on page 203 for more information on this feature, including examples on using the instance feature.

Use with Schedules

You can schedule deployments using the instance feature. See “Scheduling Deployment Instances” on page 245 for more information on this usage.

Running Deployments Asynchronously

In some situations, you may want to start a deployment but not wait for the deployment to end before moving on to other tasks. This is known as an asynchronous deployment. For example, you may have a script that starts the deployment and then proceeds to other tasks without waiting to determine whether the deployment completed.

When a deployment is run asynchronously, only the deployment’s success or failure to start is returned. No indication of the deployment’s success or failure to complete is presented. Instead, you must use another method to determine the status of the deployment, such as reviewing the log files or deployment reports.

You can run a deployment asynchronously using the -async option. For example, if you wanted to run the deployment reports asynchronously, the command would be:

iwodcmd start reports -async

When you include the -async option, the iwodcmd start command returns as soon as the deployment starts. Without the -async option, iwodcmd start would wait for completion of the deployment before returning.

Cancelling a Deployment in Progress

You can cancel a deployment in progress from the command line using the iwodcmd deploycancel command-line tool.

There are various options associated with the iwodcmd deploycancel command-line tool. Here is a listing of these options, along with the usage syntax:

iwodcmd deploycancel -h | -v

iwodcmd deploycancel deployment



deployment Name of the deployment to cancel.


Roles and Authorization

To cancel a deployment in progress from the command line, follow these steps:


od-home/bin

2. Cancel the deployment by entering the following command at the prompt:

iwodcmd deploycancel deployment [-odinst instName]

where deployment is the name of the deployment running you want to cancel in progress. For example, if you wanted to cancel the deployment reports, you would enter the following command at the prompt:

iwodcmd deploycancel reports

The deployment is stopped with no further activity.

The iwodcmd deploycancel command-line tool follows the same criteria for cancelling a deployment in progress as the browser-based user interface. See “Cancelling Deployments in Progress” on page 60 for more information.


OpenDeploy recognizes two levels, or roles, of access to the product’s features and functionality:

Administrator

User

The role an individual has determines what tasks that person can perform on specific OpenDeploy servers within the OpenDeploy environment using the browser-based user interface and Web services. These roles do not apply to running OpenDeploy from the command-line on the local host.

Administrator Role

The Administrator role allows full access to OpenDeploy configuration and functionality. The Administrator role is authorized to perform tasks that include the following:

Scheduling, starting, and cancelling all deployments.

Monitoring status of all deployments.

Viewing all schedules for deployments.

Viewing the XML source code of a deployment configuration.

Importing a deployment configuration file into OpenDeploy.

View the OpenDeploy server log.

View and upload OpenDeploy server configuration files.

Create deployment configurations.

71

Getting Started

Adding additional individuals to Administrator and User roles.

Designating which individuals holding User roles can invoke particular deployments.

Generating and access reports.

Configuring DAS.

Configuring syndication.

User Role

The User role authorizes an individual with User access to perform deployment operations on specific deployments (previously created by an individual with an Administrator role). Specifically, the User role can perform the tasks for their assigned deployments that include the following:

Scheduling, starting, and cancelling deployments.

View the schedules for the deployments.

Monitoring status.

Viewing the XML source code of a deployment configuration.

View the OpenDeploy server log.

Generating and access reports.

For example, both User1 and User2 belong to the same Web Operation user group with access to Web server mars at the operating system level. User1 is authorized to manage the deployments for the Residential Mortgage Web application, while User2 is authorized to manage the deployments for the Brokerage Web site. Both User1 and User2 have access to the same development server, but each is allowed to launch only the deployment assigned to them.



Server Access

Specifying the administrator or user server role access of an individual determines what tasks that individual can perform on a particular OpenDeploy server. You can assign and manage server role access through the user interface in the Server Access window (Figure 29).

Figure 29: Server Access Window

To assign or revoke server roles, follow these steps:

1. Select User Access > Servers to display the Server Access window.

2. Select the OpenDeploy server to which you are assigning roles from the Selected Server list.

3. Enter the individual’s user name in the Username box. If user name includes a domain, include the domain using the following syntax:domain\user

4. Click Lookup User.

The available role options are listed in the Available Roles list:

Administrator — od-admin is listed.

User — od-user is listed.

If the individual already has a role assigned on that OpenDeploy server, that role will be displayed in the Authorized Roles list.

5. Select any role you want to assign the individual from the Available Roles list, and click Add to move that role to the Authorized Roles list.

73

Getting Started

6. Select any role currently held by the individual from the Authorized Roles list, and click Remove to move that role to the Available Roles list. That individual will no longer have that role access to the server.

7. Repeat this procedure for every individual to whom you want to assign or revoke a server role.

Deployment and Deployment Groups Access

Individuals with Administrator access (od-admin) to an OpenDeploy server have unlimited access to that server’s deployments and deployment groups. See “Organizing Deployment Configurations” on page 53 for more information on creating deployment groups.

An administrator can limit the access of an individual with a User role (od-user) on that server to only those deployments and deployment groups the Administrator assigns. The same deployment or deployment group can be assigned to more than one individual with User role access on that server, and those individuals can have any number of deployments and deployment groups assigned them.

You can authorize role access to specific deployments and deployment groups associated with an OpenDeploy server through the user interface in the Deployment Authorization window (Figure 30).

Figure 30: Deployment Authorization Window



To authorize individuals with User roles to perform specified deployments on a particular OpenDeploy server, follow these steps:

1. Ensure that the user to whom you want to assign access over a deployment group has the od-user role for your OpenDeploy server. See “Server Access” on page 73 for more information.

2. Select User Access > Deployments to display the Deployment Authorization window (Figure 30).

3. Selected the OpenDeploy server whose deployment groups you want to assign from the Selected Server list.

4. Select the user name of the individual to whom you want to assign the deployment group from the Deployment User list.

Note that if the individual only has the od-admin role assigned for that server, or no od-user role at all, that user’s user name will not appear. The user must have the od-user role assigned to appear in this list.

5. Select the deployment group you want to assign access to a user from the Deployment Group list. To select the entire listed contents of the /conf directory, select “/”.

6. The deployment configurations and any sub-groups contained in the deployment group you select are displayed in the Deployment box (Figure 31):

Figure 31: Deployment Box

7. Select the item that you want to assign from the Deployment box. If you want to select the entire contents of the deployment group displayed in the Deployment Group list, select the period (“.”).

8. Click Add. The entry for the deployment group you selected is displayed in the Autho-rized Deployments box under the selected user (Figure 32).

Figure 32: Authorized Deployments Box

75

Getting Started

9. Repeat this process for each item you want to assign to the selected user. You can only assign one item at a time.

Deployment group access is recursive. If you assign a particular deployment group to a user, that user also has access to all subgroups and their deployment configurations nested within that group, including those added after the access is assigned.

Authorizing Deployments and Deployment Groups from the Command-Line

Using the iwodauthorize command-line tool, you can authorize a set of users to run a specified set of deployments and deployment groups invoked through the following methods:

Browser-based user interfaceiwodcmd start

Web services

Using iwodauthorize, you can also un-authorize users, and replace any previous authorizations with only the ones you specify.

Use of the iwodauthorize command-line tool can only be run by an individual with an OpenDeploy Administrator role for the base server being used.

The iwodauthorize tool is not applicable to deployments invoked through commands that do not use iwodcmd, such as iwodstart.

Use of the iwodauthorize command requires that you provide the following text files:

User file list — a text file containing the user names being authorized to run the deployments. Each user entry must appear on a separate line in the file, for example:

jdoerroejsmith

If domain names are required, include them using the following syntax (note use of two backslashes):

domain\\user

For example:

INTERWOVEN\\jdoe

Deployment file list — a text file containing the deployment groups and individual deployment configurations that the users are authorized to run. Each deployment name must appear on a separate line in the file, for example:

deployment1deployment2depgroup1/

Note that the deployment names should not include the .xml extension.



There are various options associated with the iwodauthorize command-line tool. Here is a listing of these options, along with the usage syntax:

iwodauthorize -h | -v

iwodauthorize -u user-filelist -d deployment-filelist -a (add | remove | set) [-odinst instName]



-u user-filelist Specifies the path to the user file list. Each user entry must be on a separate line.

-d deployment-filelist Specifies the path to the deployment file list. Each deployment group or individual configuration name must be on a separate line.

-a add Adds deployment authorizations to users in the list. These are added to any existing authorizations already present.

-a remove Removes deployment authorizations from the users in the list. Only those deployment groups and configurations in the list are removed. Any previous authorizations are retained.

-a set Resets the deployment authorizations for users in the list with only those deployment groups and configurations in the deployment list. Any previous authorizations will be lost. You can remove all deployment authorizations by specifying an empty file for the deployment-filelist value.

-odinst instName Uses OpenDeploy server instance instName.

Adding a Deployment Authorization

If you wanted to authorize the set of users listed contained in file /work/users.txt to run deployments listed in file /work/deployments.txt, you would enter the following command:

iwodauthorize -u /work/users.txt -d /work/deployments.txt -a add

The authorizations granted by this command would be in addition to any previous authorizations the users already had.

77

Getting Started

Removing a Deployment Authorization

If you wanted to un-authorize this same set of deployments from the same set of users, you would enter the following command:

iwodauthorize -u /work/users.txt -d /work/deployments.txt -a remove

This command does not remove any previous authorizations.

Resetting All Deployment Authorizations

If you wanted to reset the user list so that only the deployments contained in the referenced deployment file are included, and any previous deployments are unauthorized, you would enter the following command:

iwodauthorize -u /work/users.txt -d /work/deployments.txt -a set

If you want to simply remove all authorizations without adding new ones, use this command but reference a deployment file list that contains no entries.

Role Access in TeamSite Workflows

When including an external script to run OpenDeploy in a TeamSite workflow, the user that is running the OpenDeploy task must have the correct access to run the deployment in the task. If the user does not have the correct deployment access the deployment can fail.


Chapter 2

Deployment Types

This chapter describes the different types of deployments, and how to configure deployment configuration files.

Deployment Configuration Files

A deployment configuration file is an XML-based file containing elements and attributes that define how the deployment will work. Some elements and attribute values are required, while others are optional. In most cases, if an optional value is not specified in the deployment configuration file, OpenDeploy will use a built-in default value. In some cases, OpenDeploy will look to its base server or receiver configuration files for setting information if none exists in the deployment configuration file. The rest of this chapter discusses features available in OpenDeploy by modifying the deployment configuration file. You should have some knowledge of XML before modifying these files.

Understanding the Configuration DTDs

OpenDeploy configuration files are XML files based on the rules defined in the corresponding configuration DTD. Your XML-based configuration files must conform to the rules set forth in these DTDs.

The XML document has to meet all the well-formedness constraints given in the XML specification. Certain special characters: ('), ("), (&), (<), and (>), may appear in their literal form only when used as the following:

Markup delimiters

Within a comment

A processing instruction

A CDATA section

If they are needed elsewhere, they must be escaped using either numeric character references or the strings.

The apostrophe or single-quote character (') may be represented as “'”, the double-quote character (") as """, the ampersand character (&) as "&", the left angle bracket (<) as “<”, and the right angle bracket (>) as “>”.

79

Deployment Types

Elements

Each DTD file consists of various elements that provide some function or task. These elements are contained within angled brackets (“< >”) and form the basis of the DTD. In the source code, each element is declared in the following way:

<!ELEMENT element_name>

In many cases, a given element will have subordinate elements, knows as child elements. The child elements associated with an element are contained within parentheses following the parent element’s declaration. For example:

<!ELEMENT element_name (child_element_name)>

If an element in the source code has a child element specified, the information for that child element can be found later in the code. An element can have more than one child element. Child elements that are only separated by a space can occur in any order within the parent element. For example:

<!ELEMENT element_name (child_element_name1 child_element_name2)>

If child elements are separated by a comma (“,”), then those child elements must appear in that order within the parent element in the code. For example:

<!ELEMENT element_name (child_element_name1, child_element_name2)>

If child elements are separated by a pipe (“|”), then only one of the child elements listed can be used. For example:

<!ELEMENT element_name (child_element_name1 | child_element_name2)>

In some cases, there can be restrictions or requirements placed on the usage of elements. Certain symbols placed immediately after an element name indicate these restrictions and requirements. For example:

<element_name> (no symbol) — the element must appear just once.

<element_name?> — the element can be omitted or can occur just once.

<element_name*> — the element can be omitted or can appear one or more times.

<element_name+> — the element must appear at least once, but can occur more than once as well.


Understanding the Configuration DTDs

Attributes

Element tags can include one or more optional or mandatory attributes that give further information about the elements they support. Attributes only can be specified within the element tag. The presence of an attribute within an element tag requires a corresponding value enclosed in quotes. For example:

<element_name attribute="value">

The type of value (a number, yes|no, a path) can vary depending on the type and nature of the attribute and element. The documentation for a given attribute will specify the types of values permitted.

An element can have any number of attributes. Multiple attributes in an element tag follow one after another, with no separators. For example:

<element_name attribute_name1="value" attribute_name2="value">

The attribute declaration always immediately follows its corresponding element declaration. In the source code of the OpenDeploy configuration DTD files, the attributes of a given element are declared in the following way:

<!ELEMENT Element_name><!ATTLIST Element_name

attribute_name1 attribute1_type attribute1_keywordattribute_name2 attribute2_type attribute2_keyword>

The following sections describe attribute types and attribute keywords.

Attribute Type

The attribute type specifies the type of value that can be associated with the attribute. There are a variety of different attribute types possible. Some are immediately intuitive, such as (yes|no), where the choice is one of the values specified. Others require a more substantial explanation. Here is a list of commonly found attribute types within configuration DTDs:

CDATA — character data such as a text string. CDATA is not recognized as markup language code.

ID — an identifier for the element. No two elements can have the same ID attribute value in the same DTD. These types are usually unique identification numbers or strings.

IDREF — a pointer to an ID reference. The value must match the value of an ID type attribute that is declared somewhere else in the same DTD.

There are other attribute types possible as well. Consult a book on XML for more information.

81

Deployment Types

Attribute Keyword

The attribute keyword specifies action the server should take if an associated attribute is left out. One of the following values is used for the attribute keyword:

#REQUIRED — the attribute is required and should be present. If it is missing, the configuration file is invalid and the application will not work.

#IMPLIED — the attribute is not required. If the attribute has no value specified, the application will make a suitable substitution.

#FIXED — the attribute value is fixed at a preset value. No modification to the attribute value is allowed.

Encoding

The encoding for the nodes configuration file can be encoded other than UTF-8. For example, if a value in the file contains Japanese characters, the encoding will need to be:

<? xml version="1.0" encoding="SHIFT_JIS" ?>

For French and German, the encoding value would be:

<? xml version="1.0" encoding="ISO-8859-1" ?>

Check what the appropriate value is for any non-ASCII characters and modify the nodes configuration file encoding as needed. If no encoding is specified, UTF-8 will be used by default.

Naming Deployment Configurations

The following requirements apply to the naming of deployment configurations:

Deployment configuration file names can be any length up to the limit supported by the server’s operating system.

It is recommended that you only use alphanumeric characters for your definition name. The use of non-alphanumeric characters can result in undefined behavior.

All deployment configuration file names must have the .xml extension. The file cannot be read by OpenDeploy without this extension.

Deployment configurations residing on UNIX hosts cannot have spaces in the file names. Those running on Windows hosts may contain spaces.


Deployment Configuration Structure


All OpenDeploy deployment configurations follow the same structure. All deployment configurations begin at the root element deploymentConfiguration.

If you are using parameter substitution in your deployment, and you want to specify a parameter namespace, you can configure the parameterNS attribute for the deploymentConfiguration element. See “Parameter Namespaces” on page 207 for more information.

Within the deploymentConfiguration element are the following child elements:

localHost (required) — specifies the deployment’s server host name.

replicationFarmSet (required) — the container element for target servers and server groupings.

definition (required) — contains the source/target pairings, including the source and target file locations, and the type of deployment being performed.

deployment (required) — contains deployment features, including transactional and Deploy and Run.

logRules (optional) — specifies deployment logging settings. If no log rules are specified in the deployment configuration, OpenDeploy will reference the base server and receiver configuration files for logging instructions. If no logging information is present in those files either, OpenDeploy will use its default log settings. See Chapter 7, “Logging” on page 251 for more information.

83

Deployment Types

The following example shows a simple deployment configuration using the minimum amount of information:

<?xml version="1.0" encoding="UTF-8"?>

<deploymentConfiguration>

<logRules maxBytes="32Mb" level="verbose"/>

<localNode host="mars.mycompany.com"/>

<replicationFarmSet><replicationFarm name="web_servers">

<nodeRef useNode="MyLocalHost"/></replicationFarm>

</replicationFarmSet>

<definition name="web_files"><source>

<fileSystem><remoteDiff area="/usr/local/OD601/OpenDeployNG/conf/dtd">

<pathSpecification><path name="."/>

</pathSpecification></remoteDiff>

</fileSystem></source>

<target><targetFilesystem area="/usr/local/OD601/OpenDeployNG/tmp"/><comparisonRules dateDifferent="yes"/><permissionRules file="0644" directory="0755"/><replicationFarmLink>

<internal name="web_servers"/></replicationFarmLink>

</target></definition>

<deployment transactional="no"><execDeploymentTask useDefinition="web_files"/>

</deployment>

</deploymentConfiguration>



OpenDeploy will look to the base server (by default odbase.xml) or receiver (by default odrcvr.xml) configuration files for direction if no configuration information for a particular feature or function is present in the deployment configuration. If there is no configuration information in these files either, OpenDeploy will either use its built-in settings, or ignore the feature.

Depending on the nature and complexity of the deployment, optional elements and attributes can be added as necessary. In the following example, a variety of additional elements and attributes have been added to the previous example. However, the basic structure remains the same.

<?xml version="1.0" encoding="UTF-8"?>

<deploymentConfiguration>

<localNode host="mars.mycompany.com"/>

<replicationFarmSet><replicationFarm name="fan-out">

<nodeRef useNode="a"/><nodeRef useNode="b"><nextDeployment deployment="tier2" invokeOnSuccess="yes"/>

</nodeRef><nodeRef useNode="c"/>

</replicationFarm></replicationFarmSet>

<definition name="web_files"><source>

<fileSystem><remoteDiff area="/usr/local/OD56/OpenDeployNG/conf/dtd">

<pathSpecification><path name="this"/> <filters>

<excludePath subPath="out/exes"/><excludePattern regex="\.obj$"/>

</filters></pathSpecification>

</remoteDiff></fileSystem>

</source>

<target><targetFilesystem area="/usr/local/OD601/OpenDeployNG/tmp"/><comparisonRules dateDifferent="yes"/><permissionRules file="0644" directory="0755" user="webmaster"group="webgroup"/>

<replicationFarmLink><internal name="fan-out"/>

</replicationFarmLink></target>

</definition>

85

Deployment Types

<deployment transactional="no"><execDeploymentTask useDefinition="web_files">

<deployNRun><dnrFile location="target" when="before" state="success"

mask="\.html$"><script cmd="C:\bin\email_admin.bat -user [email protected]" where="C:\temp" async="no"/>

</dnrFile><dnrDir location="target" when="after" state="failure"

mask="images"><script cmd="C:\bin\email_admin.bat -user [email protected]" where="C:\temp" async="no"/>

</dnrDir><dnrDeployment location="source" when="after" state="success">

<script cmd="C:\bin\email_admin.bat -user [email protected]" where="C:\temp" async="yes"/>

</dnrDeployment></deployNRun>

</execDeploymentTask></deployment>

<logRules maxBytes="32Mb" level="verbose"/>


Specifying the Deployment Host

The deployment host is where the base server software sending the deployment resides. The deployment configuration must reside on the server host that will start the deployment. The deployment configuration cannot exist remotely from the source. The deployment host is specified as the localNode element’s host attribute value. For example:

<deploymentConfiguration><localNode host="mars.mycompany.com"/>...


This value must be the OpenDeploy server host’s resolvable host name or IP address. It cannot be the logical name of the host. If the host has multiple IP addresses (with one or multiple network interface cards), you must specify an IP address rather than the host name. This host must also be listed in the server’s nodes configuration file (by default odnodes.xml).

In some cases you might compose or modify a deployment configuration on your local computer, but intend to move it to an OpenDeploy base server host for actual usage. In these cases, the host attribute value must be that of the OpenDeploy base server host.


Specifying the Connection Timeout

Specifying the Connection Timeout

You can specify the time allowed for a socket connection between the sender and the targets in a deployment to time out due to inactivity. This feature gives you the capability to have your sender quit rather than waiting for a long or indefinite time if a connectivity problem occurs during the deployment.

The localNode element’s timeout attribute provides the maximum number of seconds the sending host will wait on connection inactivity with each target before stopping the deployment job. In the following example, the sending host mars.mycompany.com will wait 2 minutes before timing out and stopping the deployment:

<deploymentConfiguration><localNode host="mars.mycompany.com" timeout="120"/>...


Note that it may take as along as three times the timeout value for the deployment job to end.

A value of 0 is the equivalent of having no timeout at all. A numeric value must be provided when specifying the timeout attribute.

If a timeout occurs, the deployment is cancelled. In a fan-out deployment with multiple targets, the complete deployment fails if any one connection timeout occurs between the sending and receiving hosts.

This timeout feature is optional and pertains only to the initiating deployment host. If no value is specified, the deployment runs with no timeout limit. You must manually add the timeout attribute and its value to the localNode element. A connection is terminated regardless of whether a timeout value is used after a deployment job concludes or when the network connection is broken.

87

Deployment Types

Configuring Concurrency Management Settings

Target servers can enable the concurrency management feature to address potential conflicts and collisions resulting from simultaneous receipt of like-named files deployed into the same target file location.

Within each deployment configuration, you can set both a polling interval for the blocked deployment and a timeout amount for the deployment in the localNode element using the following attributes:

blockCheckInterval — specifies the time interval in seconds that the deployment leg waits to check for path availability. A deployment leg is the movement of a specific set of deployed files from a source file location to a target file location. After each check, the deployment reports its status back to the sending server. Default value is 30.

blockMaxWaitTime — specifies the maximum time in seconds that the deployment leg waits for a target directory to become available to receive the deployed files. When the specified time is exceeded, the deployment fails. Specify a value of 0 if you want the deployment leg to wait indefinitely until the target file location is available. Default value is 1800 (30 minutes).

In the following example:

<deploymentConfiguration><localNode host="mars" ... blockCheckInterval="5"blockMaxWaitTime="300"/>

...</deploymentConfiguration>

the deployment leg is configured to poll the target node’s blocked file location every five seconds to see if the directory is available to receive deployed files. If after 300 seconds (five minutes) the target file location still is unavailable, the deployment fails.

Refer to “Enabling Concurrency Management” on page 121 in the OpenDeploy Installation Guide for more information on this feature.


Target Replication Farms


Target replication farms are groupings of OpenDeploy target server nodes under a single named element. All target servers listed in a replication farm will receive the same set of deployed files, unless any overrides are specified. Replication farms allow you to simplify the deployment process by deploying a single set of files to multiple targets without having to individually configure each one. Each deployment configuration must have at least one target replication farm, even if that farm consists of only a single target server node. You can have as many additional replication farms as you want, as long as each one is uniquely named. An individual target server node can belong to more than one replication farm.

Specifying the Replication Farm Location

You can contain target replication farms both in the deployment configuration itself, and also in the nodes configuration file of the source server. You must indicate which replication farm you want to use by configuring the replicationFarmLink element within the target element:

<target>...<replicationFarmLink>...


Within the replicationFarmLink element are the following child elements:

internal — indicates the target replication farm to be used resides in the deployment configuration.

external — indicates the target replication farm to be used resides in the nodes configuration file of the sending server.

The internal and external elements both have an associated name attribute that references a named replicationFarm element in the deployment configuration or the nodes configuration file, respectively. In the following example, the target replication farm MyTargetReplicationFarm1 resides in the deployment configuration:

<replicationFarmLink><internal name="MyTargetReplicationFarm1"/>

</replicationFarmLink>

while in the following example, the target replication farm MyTargetReplicationFarm2 resides in the sending server’s nodes configuration file:

<replicationFarmLink><external name="MyTargetReplicationFarm2"/>


89

Deployment Types

See “Referencing Target Replication Farms in the Nodes Configuration File” on page 92 for more information on that feature.

Use of useReplicationFarm Element for Backwards Compatibility

Deployment configurations created for legacy OpenDeploy releases reference the target replication farm using the target element’s useReplicationFarm attribute:

<target useReplicationFarm="MYTARGETREPLICATIONFARM">

This method of referencing the target replication farm has been superseded by the use of the replicationFarmLink element, as described in the previous section. However, for backwards compatibility, the useReplicationFarm attribute value can still be used if there is no value specified for the internal element’s name attribute.

Configuring the Replication Farm within the Deployment Configuration

Each target replication farm is designated by the presence of a replicationFarm element.The replicationFarm element’s name attribute must contain a unique name. Within each replicationFarm element are nodeRef child elements. You must have a corresponding nodeRef element for each target server node to which you want to deploy files. Each nodeRef element must also correspond to a node entry in the nodes configuration file (by default odnodes.xml). The nodeRef element’s useNode attribute value must be the same as the target server node’s logical name (specified as the node element’s name attribute value in the nodes configuration file).

Each individual replicationFarm element is contained within a single replicationFarmSet element for the deployment configuration. In the following example, the target replication farms europe and asia are specified within the deployment configuration:

<deploymentConfiguration><localNode host="mars.mycompany.com"/><replicationFarmSet><replicationFarm name="europe">

...</replicationFarm><replicationFarm name="asia">

...</replicationFarm></replicationFarmSet>...




Within the target replication farm europe, the individual target server nodes making up the replication farm are listed, for example:

<replicationFarm name="europe"><nodeRef useNode="england"/><nodeRef useNode="france"/><nodeRef useNode="spain"/>

</replicationFarm>

These target server nodes also must be listed in the nodes configuration file for the deployment server, for example:

<nodeSet name="od_receiver_nodes"><node name="england" host="london.mycompany.com" port="20014"/><node name="france" host="paris.mycompany.com" port="20014"/><node name="spain" host="madrid.mycompany.com" port="20014"/>

</nodeSet>

Configuring Multiple References to the Same Target Host

In a deployment configuration’s target replication farm, a reference to a logical name for a target host (as specified by the nodeRef element’s useNode attribute value) can only be used once, even if that target host will receive deployments to multiple target file locations. For example, you cannot configure the following:

<replicationFarmSet><replicationFarm name="MYFARMNAME"><nodeRef useNode="mars">

<targetRules area="/dirA"/></nodeRef><nodeRef useNode="mars">

<targetRules area="/dirB"/></nodeRef>


If you want to include multiple references to the same target host, you must configure separate logical entries for the same host in the nodes configuration file (by default odnodes.xml), and then reference a different logical name for each target replication farm entry.

In the following example, the nodes configuration file contains two entries (mars1, mars2) for the same target host (mars.interwoven.com):

<nodeSet><node name="mars1" host="mars.interwoven.com" port="20014"/><node name="mars2" host="mars.interwoven.com" port="20014"/>...

</nodeSet>

91

Deployment Types

You could then use these unique logical names for each useNode attribute value in your deployment configuration:

<replicationFarmSet><replicationFarm name="MYFARMNAME"><nodeRef useNode="mars1">

<targetRules area="/dirA"/></nodeRef><nodeRef useNode="mars2">

<targetRules area="/dirB"/></nodeRef>


Referencing Target Replication Farms in the Nodes Configuration File

You can define your target replication farms in the nodes configuration file (by default odnodes.xml), and have them referenced by the deployment configuration as an alternative to defining them in the deployment configuration itself.

This method is useful if you have multiple deployment configurations deploying to the same set of targets. If there is a change in the replication farm, for example if another target server node is added, you can update the replication farm defined in the nodes configuration file. The next time any of those deployments are run, the changes in the referenced farm are applied. Otherwise, it would be necessary to update the replication farm defined in each individual deployment configuration.

Target replication farms residing in the nodes configuration file are referenced in the deployment configuration using the external element within the replicationFarmLink element:

<replicationFarmLink><external name="MyTargetReplicationFarm2"/>


Specify the unique name of the replicationFarm element residing in the nodes configuration file as the value for the external element’s name attribute value. See “Specifying the Replication Farm Location” on page 89 for more information.

Refer to “Defining Target Nodes” on page 89 in the OpenDeploy Installation Guide for more information on defining target replication farms in the nodes configuration file.

Reverse Deployments

Target replication farms can be specified in reverse deployments. The replicationFarmLink element and its child elements are defined in the reverseSource element, and are configured in the same manner. See “Reverse Deployments” on page 168 for more information on the reverse deployment feature.


Definitions

Definitions

A definition is a uniquely-named pairing of the source file location on the sending OpenDeploy server host with one or more target file locations on the receiving server hosts. The target file location specified in the definition is then applied to the target server nodes listed within the replication farm to determine which target nodes receive the deployed files, and where on the target server host’s file system those files will reside.

A definition is specified in the deployment configuration with the definition element. Its unique name is the value of the name attribute.

A definition is specified in the deployment configuration with the definition element. Its unique name is the value of the name attribute. It is recommended that you only use alphanumeric characters for your definition name. The use of non-alphanumeric characters can result in undefined behavior.

Within the definition element are the source and target child elements. For example:

<deploymentConfiguration>...<definition name="webfiles"><source>

...</source><target>

...</target>

</definition>...


Each deployment configuration must have at least one definition. You can have as many additional definitions as you want, as long as each one is uniquely named.

Source File Location

The source file location is where the source files participating in a deployment reside. This location can either be a file system location or a TeamSite area (if TeamSite is also installed on your OpenDeploy source). If the deployment is comparison-based, the source file location participates in the file comparison, either with a file system location on the target, or with another TeamSite area on the source. If the deployment is file list-based, those files that are deployed must reside in the source file location.

93

Deployment Types

The source file location is defined within the definition by the source element, and its fileSystem (for deployments originating from a file system directory) and iwStore (for deployment originating from a TeamSite area) child elements. Within the fileSystem or iwStore element is the element specifying the deployment type:

remoteDiff — a deployment based on the comparison of files residing on the source and the target host or

areaDiff — a deployment based on the comparion of files between two TeamSite areas on the source host or

filelist — a deployment based on preconfigured list of files or

payload — a deployment based on a query made of files using an adapter.

Associated with each of these deployment type elements is the area attribute. The area attribute specifies the full path to the source file location. This can either be a file system path (when the fileSystem element has been specified) or a TeamSite path (when the iwStore element has been specified. For example:

<definition name="webfiles"><source><fileSystem>

<remoteDiff area="/dev/website/files">...

</remoteDif></fileSystem>

</source>...

</definition>

or

<definition name="webfiles"><source><iwStore>

<areaDiff area="/default/main/dev/EDITION" previousArea="/default/main/dev/EDITION/IW_PREV">...

</areaDiff></iwStore>

</source>...

</definition>

In addition to specifying the area attribute, different deployment types require the configuration of additional attributes. The configuration for each deployment type is described later in this chapter.


Definitions

Specifying Particular Subdirectories within the Source File Location

You can specify one or more subdirectories within the area attribute as the source file location. This feature is useful if you want to deploy from some subdirectories within the location specified by the area attribute, but not others.

For example, if the following subdirectories reside within the area attribute value of /dev/website/files:

daily

weekly

monthly

you might only want to deploy files from the daily and monthly subdirectories, but not weekly.

You can specify the subdirectories you want to include in a deployment using the pathSpecification element, where you can specify a subdirectory within the source file location determined by the area attribute value. Each element specifying the deployment type, such as remoteDiff or filelist, must include at least one occurrence of the pathSpecification element.

Each pathSpecification element has an associated path element. This path element contains a name attribute whose value is a path relative to the area attribute, where the files participating in the deployment reside. For example:

<remoteDiff area="/dev/website/files"><pathSpecification><path name="daily">

</pathSpecification></remoteDif>

The path element’s name attribute value can be the name of a directory directly within the specified area attribute value, or a path several levels of directories deep:

<path name="daily"> or

<path name="daily/external/Q104">

You can configure multiple occurrences of the pathSpecification element, one for each distinct directory within the area attribute value. In the following example, the subdirectories daily and monthly are included in the deployment configuration:

<remoteDiff area="/dev/website/files"><pathSpecification><path name="daily">

</pathSpecification><pathSpecification><path name="monthly">


95

Deployment Types

By combining the subdirectories specified by the pathSpecification element with the area attribute value, the final source file locations for this deployment are:

/dev/website/files/daily and

/dev/website/files/monthly

If you do not want to specify a subdirectory with the area attribute value, you must still include the pathSpecification element in the configuration. You must give the path element’s name attribute the value “.”. For example:

<remoteDiff area="/dev/website/files"><pathSpecification><path name=".">


You can configure other features within the pathSpecification element, such as such as filters and rules. These features are described in Chapter 4, “Deployment Features” on page page 175.

Defining Multiple Source File Locations

You can have multiple source file locations configured within the definition. For example:


<remoteDiff area="/dev/website/files">...

</remoteDiff>

<remoteDiff area="/images">...


</source>...

</definition>

However, you should take precautions to avoid overwriting the deployed files from one source file location with those of another.

All your source file locations within a definition must be either a filesystem location or TeamSite area. You cannot combine both types within a single definition.


Definitions

Legacy Configuration Syntax for Defining the Source File Location

This release uses a newer configuration syntax for specifying the source file location and the type of deployment taking place, and is the syntax described throughout this manual. The sourceFilesystem and sourceTeamsite elements are no longer the preferred method of configuring the source file location, but OpenDeploy still supports their use, and they are contained in the deployment source DTD. Refer to your OpenDeploy 5.6 documentation if you want to continue using this legacy syntax.

Modifying Source Files During a Deployment

It is recommended that you do not modify source files while a deployment is in progress, as this can cause problems.

Target File Location

The target file location is defined within the definition by the target element. Only a single target file location is allowed in each definition. The target file location can be a file system location or a TeamSite workarea, specified by targetFilesystem or targetTeamsite elements, respectively. The associated area attribute contains the full target path, for example:

targetFilesystem area="/website/files" or

targetTeamsite area="/default/main/dev/WORKAREA/jdoe"

The target servers are not listed in the definition, only the common target file location. The target servers are listed as part of a replication farm elsewhere in the deployment configuration, or in the sending server’s nodes configuration file. Within the target element, the replicationFarmLink element references the replication farm. See “Target Replication Farms” on page 89 for more information.

The following example shows a target configuration:

<definition name="webfiles">...<target><targetFilesystem area="/website/files"/><replicationFarmLink>

<internal name="MyTargetReplicationFarm1"/></replicationFarmLink>


97

Deployment Types

Deploying to Mixed Platform Targets

Any target file location listed in a definition is assumed by OpenDeploy to apply to all the target servers listed in the target replication farms. Deployments to UNIX host will only work if you use forward slash (“/”) as path delimiter. Deployments to Windows systems will work with either forward (“/”) or backward slash (“\”) as path delimiter, since OpenDeploy converts forward slashes to back slashes on Windows. Therefore, when deploying to a replication farm containing both Windows and UNIX targets, use the UNIX (forward slash) path delimiter.

Receiving Files From Multiple Sources Simultaneously

OpenDeploy relies on the state of the target directory to remain static during a deployment. If the contents of the target directory are being modified during a deployment, then errors can occur. Running two deployments that write to the same target area is one example of this.

For best results, do not run deployments where the target file location is receiving like-named files from different source simultaneously. If there is a risk that multiple deployments will attempt to update the same target area at the same time, you should enable the concurrency management feature on the target OpenDeploy server.

See “Configuring Concurrency Management Settings” on page 88 for more information on that feature.

Configuring OpenDeploy when Target Area Is a Symbolic Link

If the target file location is a symbolic link on a UNIX host, the actual location of the received files must also be listed as an allowed directory in the receiving OpenDeploy server’s base server or receiver configuration file. For example, if the configured target file location is the following:

<targetFilesystem area="/website/files/symlink1"/>

where symlink1 points to the directory /alt/files, then both locations must be listed as allowed directories.

Additionally, if the allowed directory is a parent of the target area, then it and the directory pointed to need to be in the allowed directories list. For example, if the target area is /website/files/images and the allowed directory is /website/files, this would normally pass the allowed directory test. However, if /website/files is a symbolic link that points to /alt, then /alt must also be in the allowed directories list.

Refer to “Specifying Allowed Directories for Deployments” on page 133 in the OpenDeploy Installation Guide for more information.


Definitions

File Filters and Rules

Also included in a definition are all the rules and filters that determine what files can be deployed by the sending server and received by the target servers. These include the following:

File path exclusion filters

File name pattern exclusion filters

File comparison rules

File transfer rules

File permission rules

Transfer rules for symbolic links

Target override rules

See Chapter 4, “Deployment Features” for more information on these features, and how to configure them in your deployment.

Windows Path Naming

Acceptable source and target path naming methods vary depending of the version of Windows being used:

All supported Windows hosts can deploy to and from local drives designated by drive letter on the Windows host, such as the C: drive.

Only Windows 2000 hosts support the use of remote mapped drives designated by drive letter.

All supported Windows hosts can deploy to and from UNC path locations, such as \\host\directory.

The following table lists the path naming methods supported by Windows version:

It is recommended to use the UNC path naming method instead of remote mapped drives because they directly name the network resource that they are using.

The OpenDeploy service needs to log on as a user that has the proper network credentials to access a UNC path or mapped drive.

When using UNC path naming, you must use “$$” rather than “$” in share names that contain “$” characters.

Path Type Windows 2000 Windows 2003

Local drive letter yes yes

Remote mapped drive letter yes no

UNC path location yes yes

99

Deployment Types

Deployment Tasks

The deployment element contains attributes and child elements that allow you to configure the following items:

Transactional functionality

Definition-specific configurations for down-rev deployments and Deploy and Run scripting

Transactional

The deployment element provides the ability to make the deployment configuration transactional. If a deployment with the transactional feature enabled fails to successfully deploy all the appropriate files to the target servers, OpenDeploy will roll back the deployment and restore the target server’s file locations to their previous state. See “Using Example and Sample Configurations” on page 143 for more information.

You can enable this feature by assigning a value of yes to the transactional attribute, for example:

<deploymentConfiguration>...<deployment transactional="yes">...

</deployment></deploymentConfiguration>

Definition-Specific Configurations

Within the deployment element you can configure certain functionality on a definition-specific basis. You can specify a particular definition through the execDeploymentTask element. Each deployment element must have at least one execDeploymentTask child element. If there is only one definition in the deployment configuration, the execDeploymentTask element’s useDefinition attribute value must by that definition’s name. For example:

<deployment transactional="yes"><execDeploymentTask useDefinition="europe"/>

</deployment>


Deployment Tasks

If you have multiple definitions in a deployment configuration, then you can specify one, some, or all of those definitions with a separate instance of the execDeploymentTask element. For example:

<deployment transactional="yes"><execDeploymentTask useDefinition="europe">...

</execDeploymentTask><execDeploymentTask useDefinition="asia">...


Deploy and Run

Within the execDeploymentTask element, you can configure Deploy and Run scripts. Deploy and Run allows you to configure OpenDeploy to execute an external script at a specified stage of the deployment. This stage can be the deployment of a particular type or class of file or directory, or even the success of the deployment itself. See “Utilizing the Delivery Adapter Framework” on page 208 for more information.

Deploy and Run scripting is assigned on a definition-specific basis within the execDeploymentTask element. The deployNRun child element is the container for Deploy and Run configuration. For example:

<execDeploymentTask useDefinition="europe"><deployNRun>...

</deployNRun></execDeploymentTask>

101

Deployment Types

Directory Comparison Deployments

During a directory comparison, OpenDeploy compares the directories and files on the source with another set of files and directories residing on each target specified in the deployment’s target replication farm. The files and directories that meet the deployment criteria as a result of this comparison can then be deployed to each target server node.

In Figure 1, the source mars has a file system location defined as:

/dev/website/files

The target server node venus has a file system location defined as:

/website/files

Figure 1: Directory Comparison

Defining the Source File Location

Directory comparison deployments are determined by the fileSystem element within the source element, indicating that the source of the deployment is a Windows or UNIX file system path. Within the fileSystem element is the remoteDiff element. This element indicates that a comparison of files on different hosts (the source and target) is the method of determining which of those files are to be deployed.

<source><fileSystem><remoteDiff area="...">

...</remoteDiff>


/website/files/dev/website/files

mars venus

Comparison differences are deployed to target node.

Source and target file directories are compared.

target file system location.source file system location.



The remoteDiff element’s area attribute specifies the absolute path for a file system location containing the files. For sources, this indicates the path where the files currently reside. For example:

area="C:\dev\website\files" or

area="/dev/website/files"

Specifying TeamSite Areas

You can specify any TeamSite area as the source file location by using the iwStore element in place of the fileSystem element:

<source><iwStore><remoteDiff area="..."></remoteDiff>

</iwStore></source>

Specify the file system path to the TeamSite area you are using as the source file location as the value of the area attribute. For example:

area="Y:\default\main\dev\EDITION\ed01012001" or

area=/default/main/dev/EDITION/ed01012001

OpenDeploy also permits the use of TeamSite area paths ending in EDITION and IW_PREV as the source file location in directory comparison deployment configurations. For example:

area="/default/main/dev/EDITION" or

area="/default/main/dev/EDITION/IW_PREV"

The use of the values EDITION and IW_PREV refers to the most recent and next-to-most recent published TeamSite editions. By using the TeamSite paths for EDITION and IW_PREV, you can automatically specify the current or next-to-most current editions without having to modify the deployment configuration.

You can also include //IWSERVER at the beginning of your TeamSite area path. This component defaults the source file location to different root file system locations depending on the host’s operating system. See “Using //IWSERVER in the TeamSite Path” on page 110 for more information.

103

Deployment Types

In a directory comparison deployment configuration, the edition specified by the use of EDITION or IW_PREV would still be compared to the target file location, and the differences deployed. In the following example, a directory comparison deployment uses the TeamSite path EDITION for the source file location:

<iwStore><remoteDiff area="/default/main/dev/EDITION">...</remoteDiff>

</iwStore>

Specifying a Subpath Within the Source File Location

There may be times when you want to identify a particular location within the specified area for a deployment. You can specify locations within the source area by configuring additional elements and attributes within the source element.

The pathSpecification and path elements allow you to specify a particular relative location within the designated source area. In the following example:

<fileSystem><remoteDiff area="/dev/website/files"><pathSpecification>

<path name="monthly"/></pathSpecification>


the file system area is specified as /dev/website/files. In order to further specify the subdirectory monthly within the area, the path element’s name attribute value was specified as monthly.

The name attribute is the directory relative to the path specified in the remoteDiff element’s area attribute for your source. If you want to specify a location multiple levels below the area, you can enter the path to that location relative to the area. For example, if you want to specify the source location monthly/january relative to the area, the path element’s name attribute value would be:

<path name="monthly/january"/>



You can specify multiple pathSpecification elements with the same definition to deploy files from different subdirectories within the same specified source file location. For example, you might want to deploy files from the subdirectories monthly and weekly, but not from any other peer-level directories. You would configure this as:

<remoteDiff area="/dev/website/files"><pathSpecification><path name="monthly"/>

</pathSpecification><pathSpecification><path name="weekly"/>


You should not configure multiple pathSpecification elements in the same definition that specify the same target file location path.

The pathSpecification and path elements are required in the deployment configuration file. However, if you do not want to specify a source file location any narrower than the specified area, you can simply list the path element’s name attribute as ".", which indicates the area location. The following example shows a simple source element where no source file location is specified beyond the area:

<fileSystem><remoteDiff area="/dev/website/files"><pathSpecification>

<path name="."/></pathSpecification>


Defining the Target File Location

The target file location for a directory comparison deployment is specified by the targetFilesystem element with the target element. The targetFilesystem element and its area attribute specify the absolute path to the file system location where the target files will reside after the deployment. For example:

<target><targetFilesystem area="/website/files"/>

</target>

105

Deployment Types

After the source and target file locations are defined, the directory comparison can take place. The following example below shows the pairing between the source and target file system-based locations:

<source><fileSystem><remoteDiff area="/website/files">

...</remoteDiff>


<target><targetFilesystem area="/website/files"/>

</target>

You can use forward slashes (“/”) for the area attribute value when specifying Windows paths. See “Deploying to Mixed Platform Targets” on page 98 for more information.

Root as Target File Location

You can specify the root directory of a Windows file system (area="C:\") as a target file location of the deployment. Deployments to the root directory of a UNIX target node (“/”) are not supported.

Resolving Time Zone Differences

OpenDeploy uses Greenwich Mean Time (GMT) when performing a directory comparison deployment. This ensures the comparison of files between the sender and each target are following the same time, even if the two servers are in different time zones.

Deploying Files When Extended Attributes Change

The modification timestamp of files in a TeamSite repository is not updated when associated extended attributes (EAs) are changed. As a result, changes in a TeamSite file’s EAs would not include that file in a directory comparison deployment.

You can configure TeamSite to change a file’s modification timestamp, thus making the file eligible for deployment when the associated EAs are updated, even if the file itself has not changed.

Refer to the TeamSite 6.5 or later documentation for configuring TeamSite for modifying timestamps when EAs change.


TeamSite Comparison Deployments


In a TeamSite comparison deployment, the source files are located in a TeamSite area and are compared with a second TeamSite area, known as the previous area, in the same backing store on the source. This differs from a directory comparison deployment, where files on the source are compared with a file system location on the target node.

The previous area must be an exact representation of the contents of the target file location. The differences between the TeamSite area and the previous area are what is deployed to the target node. You can configure OpenDeploy to compare two TeamSite areas in any single backing store on a multi-backing store TeamSite server.

A common usage of TeamSite comparison deployments is to compare editions from the same branch, and subsequently deploy the changes. In Figure 2, the TeamSite server mars is publishing editions from its /default/main/dev branch. It has the most recent TeamSite edition as the value for the area attribute:

/default/main/dev/EDITION/Jan_04

The previous area is an earlier edition published from the same branch. This edition represents a mirror image of the files residing on the eventual target node venus:

/default/main/dev/EDITION/Dec_03

OpenDeploy compares the two TeamSite areas and determines which files in the more recent edition need to be deployed to the target node.

Figure 2: TeamSite Comparison Deployment

/default/main/dev/EDITION/Jan_04

Comparison differences are deployed to venus.

TeamSite area and previous area are compared.

mars venus

/default/main/dev/EDITION/IW_PREV/Dec_03

Target node file system location.

/website/files

107

Deployment Types

Defining the Source TeamSite Areas

A TeamSite comparison deployment is configured in the source element using the iwStore and areaDiff elements. The presence of the iwStore element specifies that the source file location is a TeamSite area, and the areaDiff element specifies that two TeamSite areas on the source are being compared to determine which files are subsequently deployed to the target nodes.

The areaDiff element contains both the area attribute, which typically specifies the TeamSite area with the most current files, and also the previousArea attribute, which specifies the TeamSite previous area against which those files residing in the area attribute are compared.

<source><iwStore><areaDiff area="/default/main/dev/EDITION/Jan_04"

previousArea="/default/main/dev/EDITION/Dec_03">...

</areaDiff></iwStore>

</source>

Specifying the TeamSite Area

The area attribute defines the TeamSite area where the new files to be compared are located. This area is typically an edition or a staging area. Use the path syntax associated with the for the TeamSite server’s host platform, for example:

Windows — Y:\default\main\dev\STAGING

UNIX — /default/main/dev/STAGING

Note that on Windows, the VPATH drive “Y:\” is typically used. You can specify a UNIX-style TeamSite path for the area attribute on a Windows host, but it is recommended you use the Windows syntax whenever it is practical.

Although you can deploy files from a workarea, it is not recommended, because files in a workarea do not have file versioning and other TeamSite content management features applied to them. It is preferred to submit files from a workarea to the staging area, and to perform the deployment from there.

To designate this attribute as the most recently published TeamSite edition, enter the TeamSite path ending simply with EDITION. OpenDeploy will automatically access the most recently published edition path. For example:

area="Y:\default\main\dev\EDITION" or

area="/default/main/dev/EDITION"



To specify a another edition for the area attribute, enter the complete TeamSite path to that edition. For example:

area="Y:\default\main\dev\EDITION\ed01022001or

area="/default/main/dev/EDITION/ed01022001

Specifying the Previous Area

The previousArea attribute defines the TeamSite area against which the content in the area attribute is compared. The content of the previousArea must be a mirror image of the content contained on the target node receiving the deployed files. Performing a TeamSite comparison deployment to a target in which the previous edition contains files that are different from the target location is not supported. Instead, you should perform a directory comparison- or file list-based deployment.

To designate this attribute as the edition that immediately preceded the most recently published one (as specified by the use of EDITION in the area value), enter the TeamSite path ending simply with EDITION/IW_PREV. OpenDeploy will automatically access the next-to-most recently published edition path. For example:

<areaDiff area="Y:\default\main\dev\EDITION

previousArea="Y:\default\main\dev\EDITION\IW_PREV"> or

<areaDiff area="/default/main/dev/EDITION previousArea="/default/main/dev/EDITION/IW_PREV">

To specify another edition for the previousArea attribute, enter the complete TeamSite path to that edition. For example:

previousArea="Y:\default\main\dev\EDITION\ed01012001"> or

previousArea="/default/main/dev/EDITION/ed01012001">

The two designated TeamSite areas within the areaDiff element are compared during the TeamSite comparison, and the files that meet the deployment criteria are deployed to the target node.

109

Deployment Types

In some cases, you might want to deploy the entire contents of a TeamSite area. You can perform this task by specifying a TeamSite area that contains no files as the value for the previousArea attribute, such as the initial edition that is generated for the TeamSite base branch (EDITION/INITIAL). For example:

<iwStore><areaDiff area="/default/main/dev/EDITION"previousArea="/default/main/EDITION/INITIAL"><pathSpecification>

<path name="."/></pathSpecification></areaDiff>

</iwStore>

In these types of deployments, the path element’s name attribute value can only be “.” No other locations can be specified for the name attribute.

The next section further describes the use of the path and pathSpecification elements.

Using //IWSERVER in the TeamSite Path

You can include //IWSERVER at the beginning your TeamSite path for the area and previousArea attribute values, for example:

<areaDiff area="//IWSERVER/default/main/dev/EDITION"previousArea="//IWSERVER/default/main/EDITION/INITIAL">

Inclusion of //IWSERVER in the TeamSite path translates into the following default source file location, depending on the operating system:

Windows — Y:\

UNIX — (empty string)

For example, if you specify the following on a deployment configuration:

area="//IWSERVER/default/main/dev/EDITION"

On a Windows host, the file system equivalent is:

area="Y:\default\main\dev\EDITION"

while on a UNIX host it is:

area="/default/default/main/dev/EDITION"

Using the //IWSERVER gives you a greater level of flexibility in running the same deployment on both Windows and UNIX hosts, since you do not have to change the source file location paths to reflect the host operating system.



Specifying a Location Within the Source TeamSite Area

You can specify narrower locations within TeamSite areas in the same manner as you can with file system-based areas. The elements and attributes for specifying a location within a TeamSite area are essentially the same as for a file system location. The location is relative to the area specified in the areaDiff element. However, in a TeamSite comparison deployment, the source file location is specified as a TeamSite area.

You can use the pathSpecification and path elements and their attributes to specify a location within both TeamSite areas being compared (as indicated by the values of the area and previousArea attributes), just as you did with file system-based source file locations. The relative directory or path you specify in the path element’s name attribute applies equally to the area and previousArea locations. You cannot specify a narrowed location on only one of the two areas.


<iwStore><areaDiff area="/default/main/dev/EDITION"previousArea="/default/main/dev/EDITION/IW_PREV"><pathSpecification>


</areaDiff><iwStore>

the two TeamSite areas being compared are the current edition:

area="/default/main/dev/EDITION"

and the previous edition:

previousArea="/default/main/dev/EDITION/IW_PREV"

By specifying the value monthly for the path element’s name attribute, the two TeamSite areas being compared are narrowed to the directory monthly located in each TeamSite area.

The two TeamSite areas being compared are now effectively the following:

/default/main/dev/EDITION/monthly and

/default/main/dev/EDITION/IW_PREV/monthly

111

Deployment Types

If you are deploying the entire contents of the source TeamSite area by specifying the previousArea attribute location as an empty TeamSite area (such as the initial edition that is generated for the TeamSite base branch (EDITION/INITIAL)), the path element’s name attribute value can only be “.” No other locations can be specified. For example:

<iwStore><areaDiff>area="/default/main/dev/EDITION"previousArea="/default/main/EDITION/INITIAL"><pathSpecification>

<path name="."/></pathSpecification>

</areaDiff><iwStore>


Unlike a directory comparison where the target node’s file location is an integral part of the comparison, in a TeamSite comparison the target node simply receives the deployed files. The target file location for a TeamSite comparison deployment can be either a file system location or a TeamSite workarea.

File System Target Location

Configure the targetFilesystem element and its area attribute to specify a file system target file location. For example:

<targetFilesystem area="C:\website\files"> or

<targetFilesystem area="/website/files">

You can use forward slashes (“/”) for the area attribute value when specifying Windows paths. See “Deploying to Mixed Platform Targets” on page 98 for more information.

TeamSite Target Location

Configure the targetTeamsite element and its area attribute to specify a TeamSite workarea target file location. For example:

<targetTeamsite area="Y:\default\main\dev\WORKAREA\jdoe"> or

<targetTeamsite area="/default/main/dev/WORKAREA/jdoe">

You cannot specify read-only areas like TeamSite STAGING area or EDITION as the target file location.

Use of the //IWSERVER prefix is not supported in your targetTeamsite element’s area attribute value. Use one of the following prefixes instead:

Windows — Y:

UNIX — /.iwmnt, /iwmnt, or /default



Deploying TeamSite Extended Attributes with TeamSite Files

You can include TeamSite extended attributes (EAs) in a TeamSite comparison deployment to a target TeamSite area. TeamSite extended attributes are metadata that provide additional properties information about TeamSite files. You might want to deploy TeamSite EAs along with the associated files for the following purposes:

Migrating files from one TeamSite server to another.

Synchronizing the content between multiple TeamSite servers.

Syndicating content from one TeamSite server to another for repurposing.

Refer to your TeamSite documentation for more information on TeamSite extended attributes and their usage.

Deploying EAs with TeamSite files is enabled through the targetTeamsite element’s applyExtAttrs attribute:

<targetTeamsite area="/default/main/dev/WORKAREA/jdoe"applyExtAttrs="yes">

If you specify yes for the applyExtAttrs attribute, the EAs associated with the TeamSite files are included in the deployment. The default value is no. If you specify no (or omit the attribute), the EAs are not included in the deployment.

Note: You cannot deploy TeamSite EAs to a TeamSite target where an alternate location for temporary deployed files is specified in the listernerProperties element’s transientDirectory attribute. Refer to “Specifying Alternate Locations for Temporary Deployment Files” on page 120 in the OpenDeploy Installation Guide for more information on this feature.

Comparing Files with Extended Attributes

If a file residing in a TeamSite area has associated EAs, any changes to the files’ EAs are considered a change to the file itself for the purposes of the TeamSite comparison. A file’s modification date is updated if the associated EAs are changed, even if the file itself remains the same. This change in modification date makes the file liable for deployment in a TeamSite comparison deployment.

113

Deployment Types

Writing Extended Attributes to a Manifest File

You can configure a deployment to write extended attributes (EAs) associated with TeamSite files to a target-side manifest file when the deployment is run. This feature is useful if you want to perform target-side post-processing based on EA's extracted from a Teamsite source.

Enabling or disabling this feature does not affect the deployment of the actual files themselves. You cannot configure an OpenDeploy file deployment to only generate an EA manifest file. Instead, perform a database deployment using DataDeploy if you want to only generate an EA manifest file. Refer to Chapter 5, “DataDeploy Deployments” on page 111 in the Database Deployment for OpenDeploy Administration Guide for more information on using DataDeploy.

You can configure the deployment of EAs by specifying a value of yes for the iwStore element’s recordExtAttr attribute:

<iwStore recordExtAttr="yes">

The default value is no. If you specify no, or omit this attribute from the deployment configuration, no EA manifest file will be generated.

When the deployment is run with this feature enabled, the EA manifest file is generated in the following location on the target:

od-home/log/deployment_group

If the deployment does not reside within a deployment group, then the generated EA manifest file resides in the od-home/log directory.

The EA manifest file has the following naming syntax:

rcv.deployment.definition.sourcehost.to.targetnode.logpathspec#.eamf

where pathspec# indicates the numerical order of pathSpecification elements within the definition. The initial occurrence of the pathSpecification is “0”, the following one is “1”, and so forth.

If you ran a deployment with the following characteristics:

Deployment name — gen_EAs

Definition name — def1

Source host — mars

Target host — venus

pathSpecification element order number — 0


then the following EA manifest file would be generated:

rcv.gen_EAs.def1.mars.to.venus.log0.eamf

EA Manifest File Output

The content of the EA manifest file follows the same format as the XML-based output generated from a DataDeploy deployment. For example

<?xml version="1.0" encoding="UTF-8"?>

<xml-tuple-data version="2.0.0"><data-tuple><tuple-field name="path">x</tuple-field><tuple-field name="iw_internal_area">/data/OpenDeployNG/tmp/

testcontent/alpha</tuple-field><tuple-field name="state">Original</tuple-field><tuple-field name="x">y</tuple-field>

</data-tuple><data-tuple><tuple-field name="path">y</tuple-field><tuple-field name="iw_internal_area">/data/OpenDeployNG/tmp/

testcontent/alpha</tuple-field><tuple-field name="state">Original</tuple-field><tuple-field name="y">z</tuple-field>

</data-tuple><data-tuple><tuple-field name="path">z</tuple-field><tuple-field name="iw_internal_area">/data/OpenDeployNG/tmp/

testcontent/alpha</tuple-field><tuple-field name="state">Original</tuple-field><tuple-field name="z">a</tuple-field>

</data-tuple></xml-tuple-data>

Use With Deploy and Run Scripts

You can configure a Deploy and Run script to run prior to the publishing of a TeamSite edition, and then have the TeamSite comparison deployment use this newly-created edition as the value for the area attribute. This Deploy and Run script can be configured either as a deployment-level trigger that occurs before the deployment:

<dnrDeploymentJob when="before" ...>

or as a task-level deployment-based trigger where the script is triggered before the deployment that deploys from the source at the time of connection:

<dnrDeployment when="before" triggerPoint="connect" ...>

See “Triggers” on page 216 for more information about configuring when Deploy and Run scripts in a deployment are triggered.

115

Deployment Types

File List Deployments

File list deployments rely on a pre-configured file list that determines what files are deployed, rather than through a comparison of files between file system locations or TeamSite areas. OpenDeploy deploys the files from the source file location to the target nodes based on the entries listed in this file list. The file list is a text file that you must create and make available to OpenDeploy. The path to this file is included in the deployment configuration. Only one file list per deployment is allowed.

In Figure 3, the source mars is performing a file list deployment to the target node venus. The file list resides on mars at the following location:

/OpenDeploy/fileslists/filelist1.txt

The source file location of the files on mars is:

/dev/website/files

When the file list deployment is run, OpenDeploy cross-references the file entries listed in the file list and deploys them from the source file location to the target file location on venus:

/website/files

Figure 3: File List Deployment

mars venus

Files present in the list are deployed to the target node.

/dev/website/files

File list is referenced and applicable files are selected for deployment from file system location.

Target node file system location.

/website/files/OpenDeploy/filelists/filelist1.txt




A file list deployment is indicated by the presence of the filelist element within the deployment configuration. The filelist element’s area attribute specifies the path to the source file area or TeamSite area. You must specify whether the source file location is a file system or a TeamSite area by configuring the fileSystem or iwStore element, respectively, and also include a compatible value for the area attribute. For example:

<source><fileSystem><filelist area="/dev/website/files" ...>

...</filelist>


or

<source><iwStore><filelist area="/default/main/dev/EDITION/Jan_04" ...>

...</filelist>

</iwStore></source>


You can specify a subpath within the source file location using the pathSpecification element. This feature works and is configured in the same was as for directory comparison deployments. See “Specifying a Subpath Within the Source File Location” on page 104 for more information.

Editing the File List

The file list is a text file that you can create and modify using your favorite text editor. This file contains a series of entries of files and directories whose locations are relative to the source file location specified by the filelist element’s area attribute value. Here is an example of file list entries:

www/index.htmlwww/andre/index.htmlwww/products.html

You might have to follow the path syntax of your source platform when editing the file list. Forward slashes (“/”) can be used for either Windows or UNIX hosts:

www/andre/index.html

while backslashes (“\”) are only permitted on Windows hosts:

www\andre\index.html

117

Deployment Types

Because these files and directories are relative to the specified file system, you do not need to enter the absolute path of each entry in the file list. Instead, just enter the path relative to that area attribute. For example, if you had specified the source file location as:

area="/dev/website/files"

then the entries in the file list would effectively have the following absolute path:

dev/website/files/www/index.htmldev/website/files/www/andre/index.htmldev/website/files/www/products.html

Modifying the File List During Deployments

You should not modify the file list when the file list deployment is running. This can cause problems with the deployment.

Auto-Generating Directories Not Present on the Target

If you specify a directory or subdirectory in a file list entry that is not present in the target file location receiving the deployment, that directory or subdirectory is automatically created. Any files under this auto-generated directory will also be deployed into this directory on the target. For example, if you had the following entry:

dev/website/files/www/index.html

but the target file location contained neither the file index.html nor the subdirectory /www, both would be written to the target during the deployment.

Specifying the File List

The file list is specified by the filelist element’s filePath attribute. The filePath attribute value is the full path to the file list. This value must be specified as a file system path, and the file list must reside on the source. For example:

<fileSystem><filelist area="/dev/website/files" filePath="OpenDeploy/files/filelist1.txt" ...>

...</filelist>

</fileSystem>

If the file list is inaccessible by OpenDeploy, or the contents are invalid, the file list deployment fails.




The target file location in a file list deployment functions in a manner similar to that of a TeamSite comparison deployment. The target of a file list deployment simply receives the deployed content. The target file location can be either a file system location or a TeamSite workarea. You cannot deploy files to a TeamSite STAGING area or EDITION. See “Defining the Target File Location” on page 112 for configuration information.

Configuring File List Deployments for Traversal of Target-Side Links

File list deployments to targets running on UNIX hosts can include symbolic links in the file list entries. For example, the file list entries might include the following:

dev/website/files/www/index.htmldev/website/files/www/andre/index.htmlsymlink1/products.html

where symlink1 is a symbolic link on the target host that points to another location. To instruct OpenDeploy to follow a target-side symbolic link, the following configurations must be made:

The listenerProperites element’s allowTargetFollowLinks attribute in the recipient OpenDeploy server’s base server or receiver configuration file must have a value of yes, for example:

<listenerProperties ... allowTargetFollowLinks="yes"/>

Refer to “Allowing Traversal of Target Links in File List Deployments” on page 123 in the OpenDeploy Installation Guide for more information.

The filelist element’s targetFollowLinks attribute in the deployment configuration must have a value of yes, for example:

<filelist ... targetFollowLinks="yes">

If an item in the file list is destined for a directory that is a symbolic link, such as products.html in the example file list above, this setting will instruct OpenDeploy to traverse the link on the target and deploy the item into the directory pointed to by the link.

If the target directory is deployed, such as symlink1 in the example file list above, the link is overwritten on the target host. Therefore, if the goal is to deploy a new symbolic link, then the source directory must be a symbolic link and the followLinks attribute must not be set in the sourceTransferRules element.

This feature allows a deployment to bypass the allowed directories check. Therefore, use of this feature is discouraged. As an alternative, consider setting the targetFilesystem element's area attribute to the symbolic link rather than the directory in the file list.

119

Deployment Types

For example, rather than area="/website" and file list containing symlink1/product.html, have area="/website/symlink1" and file list containing product.html. This will enable deployment into a target pointed to by a symbolic link and retain the allowed directories check.

See “Configuring OpenDeploy when Target Area Is a Symbolic Link” on page 98 for more information.

Using doDeletes with File List Deployments

File list deployments support the use of the doDeletes option. Those files that you want to be deleted at the target must be named in the deployment file list file, and must not be present in the source file location of the deployment. See “Transfer Rules” on page 190 for more information on the use of the doDeletes option.

Configuring TeamSite Source File Locations on UNIX Hosts

The following section addresses recommended methods for configuring TeamSite-based source file locations in deployment configurations when running OpenDeploy on a UNIX host.

Recommended Path Prefixes for Directory Comparison, File List or Payload Deployments

On a UNIX host, when performing a directory comparison, file list or payload deployment from a TeamSite area where the contents can change during the course of the deployment, such as a WORKAREA or STAGING area, only specify the /.iwmnt prefix for the source area. For example:

<remoteDiff area="/.iwmnt/default/main/dev/WORKAREA/jdoe">

Using the /.iwmnt prefix prevents possible inconsistencies that arise from using /iwmnt, which are caused by file and attribute caching.

Deployments from the non-cached mount point will be slower than deployments from the cached mount point. If you are deploying from a source file location whose contents are fixed, such as an EDITION, you can use the cached mount point.


Payload Adapter-Based Deployments

Recommended Path Prefix for TeamSite Comparison Deployments

When performing a TeamSite comparison deployment on a UNIX host, it is highly recommended that you only specify the /default prefix for the areaDiff element's area and previousArea attribute values. For example:

<areaDiff area="/default/main/dev/EDITION" previousArea="/default//main/dev/EDITION/INITIAL">

This will avoid threading issues that can occur during multi-legged deployments, such as fan-out and multi-definition deployments.


Payload adapter-based deployments use a payload adapter in conjunction with OpenDeploy to retrieve files from the source file location based on some selection criteria. Those files that meet the criteria are listed in a generated file manifest. OpenDeploy performs one of the following tasks using this file manifest:

The files in the manifest are compared with the files in the target and, if appropriate, deployed.

The files in the manifest are removed from the target file location. In this case, no comparison of these files with the target files occurs.

Payload adapter-based deployments can originate from arbitrary source repositories. It is the responsibility of the adapter to ensure that the files to be deployed are made accessible to OpenDeploy in a valid location. Supported locations include file system directories and TeamSite areas.

Usages of payload adapter-based deployment include providing a method of deploying code files from a software configuration management system or for deploying content files from a content management system other than TeamSite. Another usage of payload adapter-based deployment is to query a metadata repository for a list of files meeting a specific criteria for deployment or deletion.

Note: Use of payload adapters with EasyDeploy is not supported.

121

Deployment Types

Figure 4 shows how source files in a file repository are accessed by a payload adapter residing on the sending base server.

Figure 4: Payload Adapter-based Deployment

OpenDeploy provides several payload adapters for your use. Some are for evaluation to help you understand how payload adapters are structured and written, while others are provided to perform specific types of deployments. See the Appendix B, “Payload Adapters” on page 471 in the OpenDeploy Administration Guide for a listing and description of these payload adapters.

You also have the option of writing your own payload adapters. See “Writing Payload Adapters” on page 129 for more information.

A payload adapter-based deployment is indicated by the presence of the payload element within the source element of the deployment configuration.


The source file location can be either a file system location or a TeamSite area, as indicated by the fileSystem or iwStore elements, respectively:

<source><fileSystem><payload area="/dev/website/files">

...</payload>


mars venus

File system location or TeamSite area.

Files in manifest are compared with target and deployed or are deleted on target.

Payload adapter applies selection criteria to files in source file location. Selected

files are listed in file manifest.

Target file system location.

payload adapter



or

<source><iwStore><payload area="/default/main/dev/EDITION/Jan_04">

...</payload>

</iwStore></source>

The payload element's area attribute value specifies the full path to the file system location or TeamSite repository. If your data source is a repository such as a content management or software configuration management system, a location should be specified as a file system location using the fileSystem element. This is the location where files should be exported by the adapter.


You can specify a subpath within the source file location using the pathSpecification element. This feature works and is configured in the same was as for directory comparison deployments. See “Specifying a Subpath Within the Source File Location” on page 104 for more information.

Specifying the Target File Location

The target file location in a payload adapter-based deployment functions in a manner similar to that of a directory comparison deployment. Those files listed in the file manifest are compared with the files in the target file location, and the appropriate files are deployed. See “Defining the Target File Location” on page 105 for configuration information.

Specifying the Payload Adapter

The payload adapter must reside on the source of the deployment. The adapter is specified in the payLoadProperties element in the deployment configuration,

<payload ...>...<payLoadRules><payLoadProperties .../>...

</payLoadRules></payload>

or the source server’s base server configuration file (by default, odbase.xml):

<deployServerConfiguration>...<payLoadProperties ... />...

</deployServerConfiguration>

123

Deployment Types

If payload adapters are configured both in the source’s base server configuration file, and also in the deployment configuration, the deployment configuration takes precedence.

The payLoadProperties element contains the following attributes:

name — specify the name of the adapter being used, for example:

name="MyAdapter"

class — specify the adapter class, for example:

class="com.interwoven.od.adapter.retrieval.database.IWQueryDatabaseRetrieval"

parameter — (optional) specify the related parameters for the adapter to use. Separate each parameter with a comma (“,”).

This is an example of the parameters for a database payload adapter:parameter="driver=com.inet.tds.TdsDriver,

classpath=/usr/odhome/OpenDeployNG/userlib/classes12.zip,url=jdbc:inetdae7:svishward2ks:1433?database=dd, user=sa,password=, table=DEFAULT_TEAMSITE_METADATA__MASTER__MAIN_JDOE_WORKAREA_WK1"/>

where the following parameters apply:

driver — specify the payload adapter driver.

classpath — specify the path to the JDBC driver file.

url — specify the database URL.

user — specify the user name associated with the database.

password — specify the password associated with the user name.

table — specify the table name of the database. Note that for some databases, this value is not required.

Parameters are user-defined, and can vary depending on the payload adapter being used.

logLevel — (optional) indicate one of the following logging levels (consistent with log4j standards):

DEBUG — specifies fine-grained informational events that are most useful to debug an application.

INFO — specifies informational messages that highlight the progress of the application at a coarse-grained level. This is the default value.

WARN — specifies potentially harmful situations.

ERROR — specifies error events that might still allow the application to continue running.

FATAL — specifies very severe error events that will presumably lead the application to abort.



Providing Input to the Adapter

A payload adapter accepts the specification of deployment criteria based on a structure in the deployment configuration. A use case for this type of adapter is metadata-based deployment. In this case, the adapter would convert a query structure into an appropriate call to a metadata repository. Those files that match are grouped into a file manifest. OpenDeploy subsequently deploys or expires the files in the manifest.

The payLoadRules element defines the type of adapter input that is being used in the payload adapter-based deployment.

<payload ...>...<payLoadRules>...


Within the payLoadRules element you can specify one of the following elements to indicate the input type:

custom — construct the input as a PCDATA string.

query — Construct a query based on the OpenDeploy query syntax.

Within the payLoadRules element, you can specify either a PCDATA string or include the query element to pass information as input to the adapter. The PCDATA string or query details are passed to the adapter at run-time during the deployment. It is the responsibility of the adapter to process the input details.

Using a PCDATA String

If you are using an adapter that does not support the OpenDeploy query syntax, such as the GenericRetrievalExample adapter or the Intelligent Delivery module’s TQueryGenericRetrieval adapter, or an adapter that you provide yourself, you must construct the query as a PCDATA string within the custom element in the deployment configuration, for example:

<payLoadRules><custom><![CDATA[SELECT path FROM table1 WHERE name='jdoe']]></custom>...

</payLoadRules>

The syntax you use must be compatible with the payload adapter you are employing in the deployment.

If you are using parameter substitution in your payload adapter, and you want to specify a parameter namespace, you can configure the parameterNS attribute for the custom element. See “Parameter Namespaces” on page 207 for more information.

125

Deployment Types

Using the OpenDeploy Query Syntax

If you are using an adapter that supports the OpenDeploy query syntax, such as the QueryRetrievalExample adapter or the Intelligent Delivery module’s TQueryGenericRetrieval adapter, you can construct the query using the OpenDeploy query syntax. This syntax is constructed using the query element in the deployment configuration. The following section describes this syntax in detail.

OpenDeploy Query Syntax

The OpenDeploy query syntax is a query language used by certain query-based payload adapters, such as the QueryRetrievalExample adapter, or the Intelligent Delivery module’s IWQueryDatabaseRetrieval adapter. The elements and attributes associated with the query syntax are listed in the deployment query DTD. Refer to Chapter 14, “Deployment Query DTD” on page 247 in the OpenDeploy Reference for a description of this DTD.

Queries are configured in the query element, which resides within the payLoadRules element:

<payLoadRules><query>...</query>...

</payLoadRules>

Within the query element is the predicate element:

<query><predicate operator="GT" value="100">...

</predicate></query>

This element specifies a numeric- or string-based relationship between topics in a query.

The predicate element contains the following attributes:

operator — specify the type of relationship applied to the value attribute in the query. Possible values are the following:

GT — numeric value “greater than” (>)

LT — numeric value “less than” (<)

GE — numeric value “greater than or equal to” (>=)

LE — numeric value “less than or equal to” (<=)

EQ — numeric or string value “equal to (=)

NOTEQ — numberic or string value “not equal to” (/=)



CONTAIN — string value “contains”. How strings are interpreted depends on the adapter you are using. For example, if you have a payload adapter that converts the query into a SQL database call, then the CONTAIN operator might include a string with a valid SQL wildcard character.

value — specify the value associated with the operator attribute value. This value can be numeric, for example:

operator="GT" value="100" (value is greater than 100)

or the value can be a string, for example:

operator="EQ" value="politics" (value equals “politics”)

The query is further defined by the key element within the predicate element. The key element’s name attribute specifies the metadata key name, for example “test.” A key is a searchable construct within a metadata repository, such as a column name in a relational database. Within the key element is one of the following elements that defines the key data type:

textType element — indicates the value is text string.

numericType element — indicates the value is numeric.

dateType — indicates the value is a date time format. The dataType element has the following attributes:

type — specify one of the following values:

• date — indicates the day, month, and year.

• timestamp — indicates the second, minute, hour, day, month, and year.

format — specify the SimpleDateFormat Java class format for the date or timestamp (as specified by the type attribute value), for example:

dd/mm/yyyy (indicates day/month/full year) or

ss/mm/hh/dd/mm/yyyyy

You can obtain a description of the SimpleDateFormat Java class from the Sun Java API documentation Web site:

http://java.sun.com/j2se/1.3/docs/api/java/text/

SimpleDateFormat.html

The following example shows a query that is looking for terms that are equal to “MBA” (<predicate operator="EQ" value="MBA">) in the key “test” (<key name="test">). The key is identified as being text-based (textType):

<predicate operator="EQ" value="MBA"><key name="test"><textType/>

</key></predicate>

127

Deployment Types

The next example shows a query in the key “articles” for items more recent than January 1, 2000:

<predicate operator="GT" value="01/01/2000"><key name="articles"><dateType type="date" format="dd/mm/yyyy"/>

</key></predicate>

Linked Queries

You can create queries consisting of multiple predicate elements linked using the Boolean terms AND and OR. These Boolean terms are represented by the following elements within the query element:

and — specifies the combination of multiple predicate elements in the query.

or — specifies the inclusion of at least one of a group of predicate elements in a query.

Use of one of these elements requires that you include at least two occurrences of the predicate element within them. You cannot include both the and and or elements in the same query.

The following example shows a Boolean query of the key “articles” using the and element to find items whose date is later January 1, 2000 and contains the term “economics”:

<query><and><predicate operator="GT" value="01/01/2000">

<key name="published"><dateType type="date" format="dd/mm/yyyy"/>

</key></predicate><predicate operator="EQ" value="economics">

<key name="articles"><textType/>

</key></predicate>

</and></query>



Deployment Actions

You can configure what actions you want OpenDeploy to perform with the generated file manifest based on the configuration of the action element within the payLoadRules element.

<payload area="/dev/website/files"> ...<payLoadRules>...<action name="deploy"/>


The action element’s name attribute determines what action OpenDeploy takes when running the deployment based on one of the specified values:

deploy — the files in the manifest are compared with the files in the target and, if appropriate, deployed. This is the default value. If no value is specified for the name attribute, OpenDeploy runs the deployment using the default value.

expire — the files in the manifest are removed from the target file location. In this case, no comparison of these files with the target files occurs.

deployNoCompare — the files selected by the query are deployed as-is without a comparison with the target files taking place. Files are deployed and the target file overwritten, even if the source content is unchanged from the previous deployment. Bypassing source-target file comparisons in this manner enables efficient aggregation of all source files produced by a payload adapter into the target.

If the name attribute is specified with an invalid value, such as name="foo", OpenDeploy errors and the deployment fails.

Writing Payload Adapters

You have the option of writing your own payload adapter, which is a Java class, and including it in the payload adapter-based deployment.

To create a payload adapter for use in a deployment, follow these steps:

1. Add baseadapter.jar to your classpath. This jar file contains the base implementation of the adapter.

Your class should implement the interface IWODFileRetrieval (contained in basedadapter.jar) and it should contain a getFileList(String area, String xmlString, String parameter, boolean isQuery, Map adapterMap) and isAvailable() method.

You can view example classes for more information on building the adapter class. These example classes reside in the following location:

od-home/adapters/payload

129

Deployment Types

2. Add your own adapter implementation in your new class and compile it into a class file.

3. Package your Java class files into a .jar file, and place it in the following directory:


4. Add the payLoadProperties element in your base server configuration file (by default odbase.xml). Supply your class name (which is derived from IWODFileRetrieval) as the name attribute of this payLoadProperties element. See “Specifying the Payload Adapter” on page 123 for more information.

5. Restart the OpenDeploy server instance. The adapter implementation is available upon restart.

A payload adapter is invoked on the source side during the deployment.

The use of payload adapters for reverse deployments is not supported.

Metadata-Based Deployments

Metadata-based deployments use a payload adapter to determine which files to deploy based on their associated metadata.

Figure 5 shows how a metadata-based deployment works. The payload adapter queries the indexed metadata that is stored in a repository, such as a database, to select those files that match the query. Those files selected are then compared to the target file location, and the appropriate files are deployed or deleted.

Figure 5: Metadata-based Deployment

Metadata-based deployments can be performed from a TeamSite area, or another file repository. File metadata must be indexed to a database so that it is accessible by OpenDeploy. The following sections describe how to configure and run metadata-based deployments from a TeamSite area, and from an alternate type of source location.

Database containing indexed file metadata.

Payload adapter queries metadata in database. Selected

files are listed in file manifest.

mars venus

Files in manifest are compared with target and deployed or are deleted on target.

File system location or TeamSite area.

Target file system location.

payload adapter

OpenDeploy process



Metadata-based deployments using the out-of-box database adapters require that the OpenDeploy Intelligent Delivery module be licensed and enabled on your base server. Refer to “Add-On Module Licensing” on page 152 in the OpenDeploy Installation Guide for more information.

TeamSite Repositories

You can run metadata-based deployments from a TeamSite area. Those EAs associated with the TeamSite files must be indexed along with associated file paths to a database, which can be done using DAS. Refer to Chapter 4, “Database Auto-Synchronization” on page 81 in the Database Deployment for OpenDeploy Administration Guide for more information on DAS.

OpenDeploy queries the indexed EAs residing in the database using of the following Intelligent Delivery payload adapters, depending on the query method you want to use:

TQueryGenericRetrieval — use in conjunction with a query syntax that you specify in the deployment configuration as a CDATA string.

IWQueryDatabaseRetrieval — use in conjunction with the OpenDeploy query syntax.

Use of these adapters requires that the OpenDeploy Intelligent Delivery module be installed and licensed on the source. Refer to “Add-On Module Licensing” on page 152 in the OpenDeploy Installation Guide for more information.

You must configure use of either of these payload adapters in the payLoadProperties element in the deployment configuration or the source’s base server configuration file, for example:

<payLoadPropertiesname="com.interwoven.od.adapter.retrieval.database.TGenericDatabaseRetrieval"

parameter="driver=DRIVERNAME, url=URL, user=USER,password=PASSWORD/>

</payLoadProperties>

or

<payLoadPropertiesname="com.interwoven.od.adapter.retrieval.database.IWQueryDatabaseRetrieval"

parameter="driver=DRIVERNAME, url=URL, user=USER,password=PASSWORD, table=TABLENAME"/>


If you are using the IWQueryDatabaseRetrieval adapter, you must specify the table name (table=TABLENAME) as a value of the parameter attribute. See “Specifying the Payload Adapter” on page 123 for more information on configuring the payload adapter.

131

Deployment Types

For both adapters, the PATH column has to already exist in the database. These adapters assume that the database schema consists of a single table with a column for the file path names and a column for each key value (metadata name) used in the query. The PATH column can contain a path relative to the specified TeamSite area if you are deploying TeamSite assets, but should contain the full file system path if you are deploying other types of assets. All path types must be consistent. You cannot use full paths for some column entries and relative paths for other column entries.

Next, you must configure the deployment as a payload adapter-based deployment. Because the source file location is a TeamSite area, the iwStore element should be specified in the configuration:

<source><iwStore><payload area="...">

<payLoadRules>...


</iwStore></source>

If you are using the TQueryGenericRetrieval adapter, you must include the query as a CDATA string under the payLoadRules element, for example:

<payLoadRules>...<![CDATA[SELECT path FROM table1 WHERE name='jdoe']]>...

</payLoadRules>

See “Providing Input to the Adapter” on page 125 for more information.

If you are using IWQueryDatabaseRetrieval the adapter, you must include the query element under the payLoadRules element, and compose it using the elements and attributes associated with the query element, for example:

<payLoadRules>...<query><predicate operator="EQ" value="MBA">

<key name="test"><textType/>

</key></predicate>

</query></payLoadRules>

See “OpenDeploy Query Syntax” on page 126 for information on constructing queries.



Arbitrary Repositories

A metadata-based deployment can originate from arbitrary source file locations or repositories. In all cases, the source files must have metadata that is indexed to a database along with associated file paths.

You can use the DataDeploy module to deploy your files' XML-based metadata to a database. This requires that the DataDeploy module be licensed on your OpenDeploy base server. Refer to “Add-On Module Licensing” on page 152 in the OpenDeploy Installation Guide for more information.

You can use either of the payload adapters associated with the Intelligent Delivery module described in the previous section to run metadata-based deployments from arbitrary source file locations. See “TeamSite Repositories” on page 131 for a description of the payload adapters and their uses.

Configuring a metadata-based deployment originating from an arbitrary source file location requires specifying the fileSystem element in the deployment configuration, for example:

<source><fileSystem><payload area="...">

<payLoadRules>...



Metadata-Based Deployments Using Other Adapters

You have the option of using your own adapter for metadata-based deployments rather than using the Intelligent Delivery module's adapters. In some cases, such as if the metadata is stored in a proprietary repository, only a user-provided adapter will work in the deployment.

The payload adapters you implement for metadata-based deployments must accept the query as a PCDATA string, or support the OpenDeploy query syntax. Writing an adapter that supports the OpenDeploy query syntax requires that the user-defined adapter process the query XML string to convert to the syntax of customer-specific search and index engine.

You can specify the source file location as either a TeamSite area or arbitrary repository. It is the responsibility of the adapter to determine the file paths to deploy and to return those as a manifest.

133

Deployment Types

When you are writing a payload adapter for use in a metadata-based deployment, you must consider the following items:

What type of query is being employed in the deployment configuration (PCDATA or OpenDeploy query syntax)?

How will the input query from the deployment configuration be converted to a query on the metadata repository?

What is the type of source file location (TeamSite area or another location) from which the files matching the query criteria will be deployed?

See “Writing Payload Adapters” on page 129 for general information on how to write a payload adapter.

You are not required to have the Intelligent Delivery module installed and licensed if you are providing your own adapter in a metadata-based deployment.

You must specify your user-provided adapter in the payLoadProperties element in the base server configuration file. See “Specifying the Payload Adapter” on page 123 for more information.

Logging

Payload adapters have their own log files. See “Adapter Logging” on page 269 for more information.


Data Asset Deployments


You can perform a variety of data asset deployments using OpenDeploy. In some cases, you must also enable the Database module to perform certain types of data asset deployments. The following sections provide overviews of these deployment types. Data asset deployments are described in detail in the Database Deployment for OpenDeploy Administration Guide.

Database Auto-Synchronization

OpenDeploy has the ability to perform database auto-synchronization (DAS) of TeamSite extended attributes (EAs) and data content records (DCRs). DAS is a deployment mode used in the TeamSite development environment to keep metadata and dynamic content synchronized with a database that typically resides on an integration or testing server. Specific user events, such as making a change to templating content, trigger data deployments directly from the source content repository to the target database.

After you configure DAS, TeamSite data content records (DCRs) or extended attributes (EAs) are automatically deployed to a database whenever a TeamSite user performs any one of the following tasks:

Creates, changes, or deletes a data content record through the TeamSite Templating UI.

Creates, changes, or deletes a TeamSite branch, area, or file containing extended attributes through the TeamSite UI.

Figure 6 shows the sequence of events associated with DAS.

Figure 6: DAS

The modification of TeamSite DCRs or EAs results in a TeamSite event that triggers the DAS feature in OpenDeploy. OpenDeploy deploys the modified items to a database, where they can be used in the TeamSite development environment without impacting any production content.

DAS does not require any additional software license to use. DAS only supports TeamSite. Refer to Chapter 4, “Database Auto-Synchronization” on page 81 in the Database Deployment for OpenDeploy Administration Guide for more information on this feature.

TeamSite OpenDeploy database

DCR or EAs are modified

OpenDeploy uses DAS

synchronize TeamSite data with database.

TeamSite event server triggers OpenDeploy.

TeamSite data is synchronized on

the database.

135

Deployment Types

Standalone Database Deployments

A standalone database deployment accesses structured content (TeamSite metadata, TeamSite DCRs or arbitrary XML) residing on the source, and subsequently moves the content of these files to a supported relational database using JDBC.

Figure 7: Standalone Database Deployment

Figure 7 shows an OpenDeploy source that has a repository containing structured content files. When the deployment is run, the deployment configuration references a separate DataDeploy configuration file also residing on the source. The DataDeploy configuration file contains the information and settings needed to access the structured content, and copy the contents to a relational database.

Standalone deployments typically are used when you want to directly deploy structured content right into a database. Usually the database is “near” the source content, inside the same firewall. Popular use cases include writing templating data or metadata into the database.

Standalone database deployments are similar to DAS, except that instead of a TeamSite event triggering a deployment, you can run the deployment at the time and method of your choosing, such as from the browser-based user interface, through a command-line tool, and through the deployment scheduling feature. You also can deploy any type of structured content, not just those associated with TeamSite.

Standalone database deployments require that the OpenDeploy DataDeploy module be enabled on the base server. Refer to “Add-On Module Licensing” on page 152 in the OpenDeploy Installation Guide for more information.

Refer to “Standalone Database Deployments” on page 112 in the Database Deployment for OpenDeploy Administration Guide for more information on this feature.

source database

structured content files

Structured content files are deployed to relational database using JDBC



Target-Side Database Deployments

Target-side database deployments move structured content (TeamSite metadata, TeamSite DCRs, or arbitrary XML) from an source to an target (either another base server or receiver). After receiving the deployed content, the target subsequently deploys the content into a supported relational database using JDBC. The deployment configuration includes additional information that specifies how the content to be written into the database.

Figure 8 shows how a target-side database deployment works. Structured content files are deployed in the same manner as code and content files. If the deployment is comparison based, a comparison of both types of files occurs, and only the appropriate files are deployed. When the deployed files are received, the structured content is deployed to a relational database. The database type and mapping schema are referenced by the deployment configuration from other configuration files present on the source.

Figure 8: Target-Side Database Deployment

Deploying structured content in this manner allows OpenDeploy to reside closer to the target database, such as on the same LAN. Additionally, target-side database deployments allow you to take advantage of many OpenDeploy features, including the following:

Fan-out transactional deployment, which allows synchronization of files and database content.

Encrypted data transfer for secure deployment between OpenDeploy servers.

Data compression for reduced network traffic between OpenDeploy servers.

Refer to “Target-Side Database Deployments” on page 115 in the Database Deployment for OpenDeploy Administration Guide for more information on this feature.

source target database

Structured content files are deployed to target

Structured content is deployed to database. using JDBC.

137

Deployment Types

Synchronized Deployments

Synchronized target-side database deployments guarantee the collective integrity of structured content destined for a database with code and content files. Common examples include:

Files with associated metadata for use by a search engine.

Online catalog details along with web presentation templates.

Documents and personalization data for a portal.

JSP code and related data for an application server.

OpenDeploy provides a secure, flexible, and scalable solution for the cross-platform, transactional transfer of file assets to multiple servers. It can be configured to call DataDeploy to reliably and securely deliver database content along with file system assets. If any part of the deployment transaction fails, the database and files are automatically rolled back.

Figure 9 shows an OpenDeploy source that has both structured content and standard code and content files. When the deployment is run, all the files are deployed to their separate target node file locations, with structured content subsequently being deployed to the relational database.

Figure 9: Synchronized Database Deployment

source target database

Structured content files are deployed to target

Code and content files are deployed to target. XML content is deployed

to database. using JDBC.



Synchronized deployments can deploy files to multiple OpenDeploy targets as a fan-out deployment (Figure 10). However, only one target can be specified for the receipt of data asset files that are to be written to a database.

Figure 10: Synchronized Database Fan-Out Deployment

Refer to “Synchronized Deployments” on page 116 in the Database Deployment for OpenDeploy Administration Guide for more information on this feature.

source target

target

target

XML content is deployed to database. using JDBC.

Code and content files are deployed to target.



database

Structure content files are deployed to target

139

Deployment Types

Defining Source-Based Overrides

You can override global target-side attributes, such as the target file location and certain rules and filters, with alternate attributes on a source-level basis. This feature allows files in a specified source file location to be deployed to an alternate target file location, and also overrides any existing target-side rules or filters. You can also use this feature to deploy a single set of files to multiple target file locations within the same deployment configuration.

One use of source-based overrides is when there are metadata files associated with a set of deployed files. You might want to also deploy those metadata files, but to a different target file location. By specifying this alternate target file location in conjunction with the metadata source file location, you can deploy both the main files and the metadata files within the same definition.

Source-based overrides are specified in the targetRules element. When this element is present in the deployment configuration, OpenDeploy will override the target file location in the targetFilesystem element and both compare (if necessary) and send the files to the path location specified as the targetRules element’s area attribute value instead.

The targetRules element resides within the pathSpecification element associated with the element defining the deployment (remoteDiff, areaDiff, filelist, and payload). Each of these elements can have one occurrence of the targetRules element within each occurrence of the pathSpecification element.

The following example illustrates how a source file location can compare and deploy files to an alternate target file location (D:\metadata\files) at the same time another source file location deploys to the standard target file location (D:\website\files), all within the same definition:

<source><fileSystem><remoteDiff area="C:\website\files">

...</remoteDiff>

<remoteDiff area="C:\metadata\files"><pathSpecification>...<targetRules area="D:\metadata\files"/>



<target><targetFilesystem area="D:\website\files">

<replicationFarmLink><internal name="web_farm"/>



Defining Target-Based Overrides

You can specify source-based overrides for the following OpenDeploy features:

Filters

Transfer rules

Comparison rules

Permission rules

See Chapter 4, “Deployment Features” for more information on these features.

Defining Target-Based Overrides

There are a variety of situations where the single set of values specified in the target element of a deployment configuration cannot apply to all the target nodes in a multi-target deployment equally or successfully. These situations include:

A different target file location is required for one or more target nodes.

Features need to be added or modified on a target-specific basis.

Specifying Different Target Areas

You can also use this feature to specify different target node file locations even when the source and target nodes are all of the same platform. In the following example, the target nodes mars, jupiter, and saturn are all Windows servers.

<replicationFarmSet><replicationFarm name="MYFARMNAME"><nodeRef useNode="mars"/><nodeRef useNode="jupiter">

<targetRules area="c:\website\western"/></nodeRef><nodeRef useNode="saturn">

<targetRules area="c:\website\eastern"/></nodeRef>


Using the same targetFilesystem element and area attribute values from before, mars accepts that area location to receive the deployed files, while jupiter and saturn each override that location with ones unique to their own file systems.

141

Deployment Types

Defining Features on a Target-Specific Basis

You can specify certain features to apply to particular target nodes. A feature defined within the nodeRef element for a target nodes overrides any comparable feature or attribute value defined within the target element of the deployment configuration, as well as any source-based overrides specified within the pathSpecification element. Within each nodeRef element you can add additional elements to specify features for that target node including:

Filters

Transfer rules

Comparison rules

Permission rules

See Chapter 4, “Deployment Features” for information on these features.

Deployment Logging

Logging settings in a deployment configuration affect the following types of log files:

Source macro log

Source micro log

Receiver macro log

Receiver micro log

Base server and receiver log files are not affected by logging settings present in deployment configurations.

You can specify the following logging rules in a deployment configuration:

Rollover threshold size for a deployment’s micro and macro log files

Logging level

One or both of these settings will override any equivalent settings present in the base server or receiver configurations as they apply to deployment logs. Logging level settings in a deployment configuration can be overridden only when a different level is specified when a deployment is started manually in the OpenDeploy user interface, or by using the iwodcmd start command.

You cannot specify a different log file location in a deployment configuration. That functionality only exists in the base server or receiver configurations files.

See Chapter 7, “Logging” on page 251 for a complete description of how OpenDeploy logs deployments, and on how to manage your log files.


Using Example and Sample Configurations

Using Example and Sample Configurations

OpenDeploy provides a variety of configuration examples and samples. You can use these examples and samples both to learn and better understand the deployment configuration structure and syntax, and also as the basis for composing your own deployments. Because XML-based deployment configuration files must be syntactically correct to work, writing new deployment configuration files can result in a large amount of troubleshooting. By knowing which parts of an example or sample deployment configuration file to modify for your use and which parts to leave alone, you can become productive more quickly and avoid many problems.

Example Configurations

Example configurations are provided for a number of different types of deployments. Each example file contains numerous comments explaining the elements and attributes that make up the configuration.

Example files are located on your OpenDeploy server at the following location:

od-home/(od-instance)/conf/examples

A README file is included describing each example file. Later in this section, you will open one of these example configurations and modify it to use within your enterprise.

Sample Configurations

Sample configurations are a set of deployment configurations designed to allow you to modify them quickly and easily to use within your enterprise. The sample configurations use a common set of variable names that let you modify and test different types of deployments. An accompanying README file provides instructions on how to modify the sample configurations for use within your enterprise.

Sample files are located on your OpenDeploy server at the following location:

od-home/(od-instance)/conf/examples/samples

143

Deployment Types

Redeploying Legacy Web Sites

If you are using OpenDeploy in conjunction with TeamSite, you can make a copy of a set of deployed files and store it for later use. This feature is handy if you need to “roll back” an existing Web site to a previous version, or recreate a Web site as it once looked. When a set of Web files on a TeamSite server is complete and ready to deploy, make a TeamSite edition of those files. Include the date or some other identifying element in the edition name. Later, if you need to recreate a legacy Web site, you can deploy that saved edition.

You can deploy the TeamSite edition using the TeamSite comparison method. Specify the area attribute value as the path to the TeamSite edition you want to deploy. Specify a TeamSite area that contains no value for the previousArea attribute, such as the initial edition that is generated for the TeamSite base branch. When the deployment is run, all the files in the TeamSite edition you need to restore your legacy Web site will be redeployed to the target node. See “TeamSite Comparison Deployments” on page 107 for more information.


Chapter 3

Content Delivery Methods

This chapter describes the different methods available for moving content between the source and targets. In most cases, these delivery methods can be used in conjunction with any of the deployment types described in the previous chapter.

Transactional Deployments

Transactional deployments give you an added level of security for maintaining the integrity of your Web sites during deployments by automatically rolling back a deployment and restoring the target files to their previous states in the event one or more target deployments fail.

Transactional deployments are particularly useful where a number of recipient targets must have their Web sites synchronized with each other. If one or more of the deployments to these targets fail, it may be preferred to restore some or all of them (even the targets whose deployments succeeded) back to their previous states until another deployment can be attempted.

In Figure 1, the source mars attempts a transactional deployment to the target venus. The deployment can be of any type. During the deployment, file transmission to the target is interrupted halfway through the process and is considered to be a failed deployment. After OpenDeploy becomes aware that this transactional deployment has failed, it restores venus’ file area containing the deployed files back to its original state.

Figure 1: Transactional Deployment

mars venus

OpenDeploy references a transactional deployment configuration.

Deployment of files to venus is unsuccessful, and is detected by OpenDeploy.

OpenDeploy restores venus’ file area to its original state with no content change noticeable.

145


Transactional deployments are enabled only in the deployment configuration file an attribute of the deployment element. Give the value yes if you want the deployment to be transactional. For example:

<deployment transactional="yes">

Fan-out deployments can use the transactional feature to roll back a deployment and restore files on multiple targets. Similarly, multi-tiered deployments can use the transactional feature to roll back deployments across tiers. See “Transactional Targets in Fan-Out Deployments” on page 147 and “Transactional Targets in Multi-Tiered Deployments” on page 152 for more information.

Fan-Out Deployments

OpenDeploy can deploy the same set of files to multiple targets as part of a single deployment. Deploying to multiple targets in this way is called a fan-out deployment. Fan-out deployments are often preferred if your organization has several production Web servers, each of which must have its Web content synchronized with the others. A fan-out deployment automatically deploys to all targets simultaneously with no more effort on your part than if you were deploying to a single target.

The same deployment configuration used to deploy files to a single target can be modified to include all targets. Any type of deployment can be used, and all deployment rules and features are allowed in fan-out deployments. Although deployment to each target is identical by default, you can also modify the fan-out deployment configuration to allow exemptions to the rules on a target-specific basis.

In Figure 2, the source mars performs a fan-out deployment to three mirrored production servers: venus, jupiter, and mercury.

Figure 2: Fan-Out Deployment

OpenDeploy references a fan-out deployment configuration.

mars

venus

jupiter

mercury

Files are deployed to targets.


Fan-Out Deployments

You configure fan-out deployments using one of the following methods:

Use multiple nodeRef elements within the replicationFarm element:

<replicationFarm ...><nodeRef useNode="venus"/><nodeRef useNode="jupiter"/>

</replicationFarm>

The useNode attribute value in a nodeRef is the logical name for a specific target. That logical name must appear in the sending OpenDeploy server’s nodes configuration file (by default odnodes.xml).

Use multiple execDeploymentTask elements, each of which can reference a named definition element. That element in turn specifies a grouping of one or more source file locations with a single target file location:

<deployment ...><execDefinitionTask useDefinition="MyFirstDef"/><execDefinitionTask useDefinition="MySecondDef"/>

</deployment>

The useDefinition attribute value in an execDefinitionTask element references a particular definition elements in the configuration, and deploys files specified within that definition element when the deployment is run.

EasyDeploy

Fan-out deployments are not supported by the EasyDeploy base server software. To use fan-out deployments, you must upgrade to the full-feature base server software.

Transactional Targets in Fan-Out Deployments

Because it is often required that all the targets in a fan-out deployment are mirror images of each other as well as the source, it might be preferable not to deploy files to any of the targets in a fan-out deployment, unless a percentage of the targets, or one or more targets in particular, successfully receive the files. If any target does not receive its deployed files successfully, that deployment is considered to be a failure. You can restore those targets that did receive deployed files back to their previous existing states by enabling the transactional feature. See “Transactional Deployments” on page 145 for more information.

You can designate all targets to be transactional in a fan-out deployment by specifying a value of yes for the transactional attribute in the deployment element of the fan-out deployment configuration. For example:

<deployment transactional="yes">

147


In Figure 3, the source mars performs a deployment-wide transactional fan-out deployment to two targets: jupiter and venus. Although the deployment to jupiter was successful, the deployment to venus failed. Because this fan-out was transactional on a deployment-wide basis, after the deployment was determined to be a failure, mars automatically restores both the targets.

Figure 3: Transactional Fan-Out Deployment

Determining the Success Criteria (Quorum)

A fan-out deployment can be considered successful even if all the targets do not receive the deployed files successfully. You can specify how many targets of a fan-out deployment must receive the deployment successfully for the overall deployment to be considered a success using the quorum feature. A quorum is a value specified in the deployment configuration that states a minimum number of targets that must receive all the deployed files successfully for OpenDeploy to consider the deployment a success. A deployment deemed as successful in this manner will not trigger the transactional feature (if enabled) that rolls back the deployment and restores all the fan-out targets to their previous states. If the quorum number is not met, all the target’s deployments are rolled back.

You can specify the quorum number as a value for the quorum attribute in the replicationFarm element. For example:

<replicationFarm name="fan-out" quorum="2"><nodeRef useNode="venus"/><nodeRef useNode="jupiter"/><nodeRef useNode="mercury"/>

</replicationFarm>

The number your specify for the quorum can never exceed the number of targets specified as nodeRef element entries in the replicationFarm element. The quorum feature is not supported if the deployment configuration contains multiple replicationFarm elements.


jupiter

venus

Deployment of files to jupiter is successful.

Overall fan-out deployment is unsuccessful, jupiter is restored.

Deployment of files to venus is unsuccessful, and is detected by OpenDeploy.

marsOpenDeploy restores venus’ file area to its original state with no content change noticeable.


Multi-Tiered Deployments

In Figure 4, the deployment has a quorum value of 2, meaning at least two of the targets must receive the deployed files successfully.

Figure 4: Fan-Out Deployment using Quorum and Transactional Features

If the number of successful target deployments does not meet the quorum value, OpenDeploy considers the deployment a failure. Since the transactional feature is enabled, OpenDeploy rolls back the deployment and restores all the targets, even the one that might have otherwise received its files successfully.


A multi-tiered deployment is a deployment where one or more of the targets use their OpenDeploy base server software to redeploy the files to a new group of targets. Each combination of source and targets is known as a tier. Any target that redeploys received files must have the base server software installed to send files. The next-tier source redeploying the files references its own deployment configuration files for the next-tier deployment.

Each sending base server on each tier participating in the multi-tiered deployment must contain the appropriate deployment configuration associated with that tier. The original deployment configuration information is not transmitted from the first source to the next-tier source as part of the deployment. Instead, you must configure the deployment at each sending server on each tier prior to running the multi-tiered deployment. Any combination of deployment types and OpenDeploy features can be utilized in a multi-tiered deployment. There is also no limit to the number of tiers that can be included, as long as each tier has at least one base server.


mars

venus

jupiter

mercury

Files are deployed to targets.

quorum=2transactional=yes

149


In Figure 5, the source mars deploys a fan-out deployment to its targets: venus, jupiter, and mercury. This represents the first, or current, tier. The targets venus and mercury have the receiver software installed, allowing them only to receive deployments. However, jupiter has the base server installed and can send as well as receive deployed files. After it successfully receives the files deployed from mars, jupiter references its own deployment configuration file and redeploys the files to its own targets: saturn and pluto. The source jupiter and its targets represent the second, or next, tier.

Figure 5: Multi-Tiered Deployment

Any targets with the base server software installed can start their own deployments, passing on the same deployment data to new targets. This process of redeploying files can continue indefinitely if every tier has a base server capable of redeploying the files it receives.

The role of the source server originating the deployment stops after its targets successfully receive the deployed files. The sending base server at the second tier now takes over, and its deployment configuration file determines the scope and functionality of the deployments on this tier. The second-tier sending base server also does not receive any deployment configuration information from the current-tier base server.

A base server that is intended to participate in multi-tiered deployments as a secondary- or later-tiered sending server must have its deployment configuration file properly configured before the deployment.

mars jupiter

venus

mercury

saturn

pluto

Files are deployed to targets. Files deployed to the targets.

OpenDeploy on mars references a fan-out deployment configuration and deploys to first tier of targets.

OpenDeploy on jupiter references its own deployment configuration and redeploys received files to next tier of targets.



A deployment is configured as being multi-tiered by the presence of the nextDeployment element associated with one or more of the sending server’s targets as specified in the replication farm:

<replicationFarm name="multi-tiered"><nodeRef useNode="venus"><nextDeployment deployment="tier2_deploy" invokeOnSuccess"yes"

multiTierTransactional="no"/></nodeRef><nodeRef useNode="jupiter"/><nodeRef useNode="mercury"/>

</replicationFarm>

A target base server of the original deployment that is intended to run a next-tier deployment will have the nextDeployment element and its attributes configured in the target base server’s nodeRef entry in the replication farm.

The nextDeployment element has the following attributes:

deployment — enter the name of the deployment that will execute on the target base server upon completion of this current deployment. The deployment name will be the same as the deployment configuration file. For example, if the name of the deployment configuration to be invoked is tier2_deploy.xml, then the value would be:

deployment="tier2_deploy"

That specified deployment configuration must be present on the associated target base server for that server to run the next-tier deployment.

invokeOnSuccess — indicate whether (yes) or not (no) the next-tier deployment should be invoked. If the value is yes, then the next-tier deployment is invoked if the current-tier deployment is successful. If the value is no (the default value), the next-tier deployment is not invoked.

multiTierTransactional — indicate whether (yes) or not (no) the transactional feature is enabled for the multi-tiered deployment. If enabled, in the event a specified number of targets fail to successfully receive their deployments, the deployments to all the targets are rolled back and their original files are restored. The default value is no. See “Transactional Targets in Multi-Tiered Deployments” on page 152 for more information.

In the following example, a sending server in a multi-tiered deployment has configured its target venus (itself a base server) to run a next-tier deployment after receiving the deployed files:

<replicationFarm name="multi-tiered"><nodeRef useNode="venus"><nextDeployment deployment="monthly" invokeOnSuccess"yes"/>

</nodeRef>...

</replicationFarm>

151


This configuration indicates the following:

The deployment configuration that will be used is monthly, and that the configuration for monthly (monthly.xml) resides in the od-home/(od-instance)/conf directory of the node that will redeploy the files.

The next-tier sending server venus only can run the deployment if the overall current-tier deployment is successful.

The absence of the multiTierTransactional attribute indicates that the deployment is not transactional across tiers. The absence of the attribute is the equivalent of specifying a value of no.

EasyDeploy

Multi-tiered deployments are not supported by the EasyDeploy base server software. To use multi-tiered deployments, you must upgrade to the full-feature base server software.

Transactional Targets in Multi-Tiered Deployments

Multi-tiered deployments are supported by the transactional feature. Each sending server on each tier participating in the multi-tiered deployment must have this feature enabled in its respective deployment configuration for the overall deployment to be rolled back in the event the deployment is unsuccessful.

If the criteria for a successful deployment between a single sending server and its targets is not met (as determined by the success criteria), the sending server reports to the sending server at the previous tier from which it received its deployment of the failure. The report of failure is sent back to the originating base server where the deployment started, which in turn informs the remaining sending server in the subsequent tiers that the deployment failed. This process continues among each sending server across the tiers until all have received the report of failure. OpenDeploy does not commit a multi-tiered transaction until all participating servers report success. If a report of failure is received, the commit does not take place, and all servers roll back the deployment and restore the targets to their original states.

The transactional feature is enabled in multi-tiered deployments by the nextDeployment element’s multiTierTransactional attribute.

<nextDeploymentdeployment="monthly"invokeOnSuccess="yes"multiTierTransactional="yes"/>

If you specify a value of yes for the multiTierTransactional attribute, the next deployment is included in the multi-tiered transaction.



The multiTierTransactional attribute must be present and enabled in each sending server’s deployment configuration for a deployment to participate in the multi-tiered transaction.

Figure 6 shows how the transactional feature is used in a multi-tiered deployment. Content is deployed from mars to the targets base server jupiter and the receivers venus and mercury. The base server jupiter deploys the content at the next tier to the target receivers saturn and pluto. Each target indicates success if the files were deployed successfully, or failure if there was a problem. If all deployments are successful, then all targets commit the deployed content. If any sending server reports a failure, the targets roll back the deployed content and restore their files to their previous state.

Figure 6: Use of the Transactional Feature in Multi-Tiered Deployments

Use with Quorum

You can use the quorum feature to specify how many targets must receive their deployments from each sending server at each tier to determine whether the overall deployment is successful or not in a multi-tiered transactional deployment. However, to use the quorum feature, your deployment configuration can contain only one definition. Multiple definitions are not supported. See “Determining the Success Criteria (Quorum)” on page 148 for more information on the quorum feature.

Restrictions

You cannot configure a deployment to be multi-tiered (through inclusion of the nextDeployment element) if your deployment contains multiple definitions that have the same target. This is because the multi-tiered deployment feature activates as each definition is run, rather than waiting until all definitions within the deployment are completed.

mars jupiter

venus

mercury

saturn

pluto

Multi-tiered deployment runs where every sending server at each tier has multiTierTransactional="yes" configured.

153


The following example shows a deployment with two definitions, both deploying to the same target, as specified by the replication farm reports. As configured here, this deployment cannot work.

<deploymentConfiguration>...<replicationFarmSet><replicationFarm name="reports">

<nodeRef useNode="mars"><nextDeployment deployment="nextTier" invokeOnSuccess="yes"

multiTierTransactional="no"/></nodeRef>


<definition name="def1"><source>

<fileSystem><remoteDiff area="/dev/accounting/reports">



</fileSystem></source><target>

<targetFilesystem area="/dev/external/reports"/><replicationFarmLink><internal name="reports"/>




<fileSystem><remoteDiff area="/dev/finance/reports">




<targetFilesystem area="/dev/internal/reports"/><replicationFarmLink><internal name="reports"/>


</definition>...


Here, after the files specified in the definition def1 are deployed, the next-tier deployment nextTier would be run without waiting for the files in definition def2 to be deployed.



The following example shows a proper way to configure this deployment using source-based overrides:

<deploymentConfiguration>...<replicationFarmSet><replicationFarm name="reports">

<nodeRef useNode="mars"><nextDeployment deployment="nextTier" invokeOnSuccess="yes"

multiTierTransactional="no"/></nodeRef>



<fileSystem><remoteDiff area="/dev/accounting/reports">

...</remoteDiff><remoteDiff area="/dev/finance/reports">

<pathSpecification><path name="."/><targetRules area="/dev/internal/reports"/>



<targetFilesystem area="/dev/external/reports"/><replicationFarmLink><internal name="reports"/>


</definition>...


Here, a single definition def1 is used, but it includes multiple remoteDiff elements. Each remoteDiff element can override the target file location specified by the targetFilesystem element with its own target file location as specified by the targetRules element’s area attribute.

In this example, the first occurrence of the remoteDiff element deploys files to the default target file location as specified by the targetFilesystem element’s area attribute value:

<targetFilesystem area="/dev/external/reports"/>

However, the second occurrence of remoteDiff overrides the default target file location with a different one specified by its targetRules element’s area attribute value:

<targetRules area="/dev/internal/reports"/>

155


Because only one definition is included in this deployment, the nextDeployment element can be included in the configuration, making this a multi-tiered deployment.

Routed Deployments

Routed deployments are similar to multi-tiered deployments in that they permit content to be deployed across multiple next-tiers of base servers until they reach their final destination. Each tier can deploy to base server and receiver targets, although only base servers can move content to the next tier.

Routed deployments differ from multi-tiered deployments in that the base server at each tier does not require its own pre-installed deployment configuration file be in place prior to the start of the deployment. Instead, a list of allowed tier-to-tier routes, known as route segments, resides in the nodes configuration file (by default odnodes.xml) of the source server originating the routed deployment. This list of route segments provides the basis for computing a route from the originating source to each end target.

A group of route segments is a route definition that together specify a complete path from the originating source server to all the intended targets. You can configure multiple route definitions for use in different deployments, and the same route segment can be used by different route definitions. When you configure a routed deployment, you reference the particular route definition that can direct the deployed content from tier to tier until the deployment is completed.

Route definitions and route segments must be configured in the nodes configuration file of the originating deployment server prior to starting a routed deployment.

Figure 7 shows a routed deployment originating from the source mars.

Figure 7: Routed Deployment

mars jupiter

venus

mercury

saturn

pluto

Allowed route segments:mars —> venus

venus —> jupiter

mars —> mercury

mercury —> jupiter

jupiter —> saturn

jupiter —> pluto


Routed Deployments

To deploy to each target in the illustration, the following allowed route segments would have to be listed in mars’ nodes configuration file:

mars —> venus

venus —> jupiter

mars —> mercury


jupiter —> saturn

jupiter —> pluto

In some cases, the exact route may not be known. However, regular expressions can be incorporated into the list of route segments that can check the nodes configuration files of next-tier base servers to see if those servers have the route specified. See “Resolving Unspecified Routes” on page 159 for more information.

How Route Definitions Are Determined

OpenDeploy determines the route definition for each end target by joining the allowed route segments starting with the end target, and working backwards to the originating source server, until an uninterrupted circuit is constructed.

The logical name of the originating server is used to establish the beginning of the route definition. This logical name is specified by the localNode element’s name attribute value in the originating base server configuration file (by default odbase.xml).

OpenDeploy searches those allowed route segments listed in the originating source server’s nodes configuration file that have the end target as the destination. If a routed deployment from originating source mars to end target saturn is specified, OpenDeploy reviews each route segment looking for saturn as the destination. OpenDeploy searches the allowed route segments from the top down, and stops with the first match. Using the example associated with Figure 7, the first (and only) match would be jupiter —> saturn. If the allowed route segment mars —> saturn was also present in the following order:

jupiter —> saturn

mars —> saturn

OpenDeploy would still select jupiter —> saturn because it is the first match in the list of allowed route segments.

157


After the initial allowed route segment to the end target is selected, OpenDeploy then continues backwards to the previous tier looking for another matching allowed route segment that will continue the route circuit to the originating source. The source of the first route segment (jupiter) found becomes the destination of the next search. Again, OpenDeploy searches the route segments from the top down, and stops the search at the first match.

This process continues through each tier until a complete circuit from the end target (saturn) to the source (mars) is constructed. If OpenDeploy reaches a point where the circuit cannot be continued to the previous tier (and therefore the originating source server) the routed deployment fails.

Route Optimization

If more than one route is determined due to multiple destinations being specified in the deployment, OpenDeploy then compares the computed routes to determine if there are redundancies so that they can be eliminated. For example, if the following routes were determined:

mars —> mercury —> jupiter —> saturn

mars —> mercury —> jupiter —> pluto

the optimization would yield mars —> mercury —> jupiter —> (saturn and pluto). In this way, only one deployment of content goes from mars —> jupiter rather than two parallel ones, resulting in a more efficient deployment.

Route Strategies

Because OpenDeploy searches the allowed route segments from the top down and stops at the first match, you must configure the route segments in the originating source server’s nodes configuration file so that your preferred route segments are listed above those that are less favored.

For example, if you wanted the routed deployment to move through mercury rather than venus, you would have to configure the route segment so that the mercury —> jupiter segment came before the venus —> jupiter segment:

mars —> mercury


mars —> venus

venus —> jupiter

jupiter —> saturn

jupiter —> pluto


Routed Deployments

Whether to configure a single route definition with all the possible allowed route segments, or whether to configure several different route definitions, each with a different collection of route segments, depends on your deployment requirements and network structure.

You can create route definitions that favor or avoid the movement of deployed content through certain targets. If you are deploying very large amounts of content during times of peak network usage, you might not want to include a busy target, or one with lesser performance, in the route definition. However, that same target might be fine for routed deployments during other times.

Using Third-Party Adapters

Route computation is performed by a default routing adapter. You can implement your own adapter for computing routes through the use of a user-provided adapter.

Specifying End Targets

The end targets of a routed deployment are those servers specified in the deployment configuration’s replication farm set. In Figure 7, the replication farm set for that example would be the following:

<replicationFarm name="end_targets"><nodeRef useNode="venus"/><nodeRef useNode="mercury"/><nodeRef useNode="saturn"/><nodeRef useNode="pluto"/>

</replicationFarm>

See “Target Replication Farms” on page 89 for more information on replication farms and their configuration.

Resolving Unspecified Routes

In some cases, you may not be able to list all the route segments required to move content from its source to its final destinations. Instead, you may only be able to specify the allowed route segments to a midway point and must rely on the next-tier target in the routed deployment to continue the deployment. For example, you might be able to route a deployment to an entry point of a LAN, but not know the individual targets on that LAN that need to receive the content.

You can configure your routed deployment for this scenario by incorporating regular expressions in your allowed route segment naming that can be used in conjunction with the nodes configurations of the next-tier OpenDeploy server.

159


Figure 8 shows a routed deployment from mars to england, which is the gateway to a LAN with four additional OpenDeploy targets.

Figure 8: Routed Deployment Using Route Segment Using Regular Expressions (ex. 1)

The route segments in the nodes configuration file on mars are able to move the content as far as england (mars —> england), but not beyond to the appropriate targets on the LAN. The nodes configuration on england contains the allowed route segments to move content from england to each target on the LAN:

england —> londonExt

england —> londonInt

england —> scotlandA

england —> walesZ

To permit the deployed content to reach its intended destination, the nodes configuration on the source mars must be configured to use the nodes configuration on the next-tier target england to specify which targets are to receive the content after it reaches england.

Specifying a regular expression in the route segment on the source’s nodes configuration directs OpenDeploy to compute a route at the next-tier target using that server’s nodes configuration. The next-tier target’s configured route segments can then continue the content either to another next-tier target, or to the content’s final destination.

mars england

londonExt

walesZ

londonInt

scotlandA

Allowed route segments:mars —> england

england —>london.*

england —>scotland.*

england —>wales.*

Allowed route segments:england —> londonExt

england —> londonInt

england —> scotlandA

england —> walesZ


Routed Deployments

Regular expressions are specified in the route segments configuration using (“.*”) character. To move the deployed content from mars to england, and on to all the targets allowed by england’s allowed route segments configuration, you would configure the following route segments in mars’ nodes configuration:

mars —> england

england —> london.*

england —> scotland.*

england —> wales.*

File Manifest Determination

The manifest of files that are deployed from the source to the final destinations in a routed deployment vary depending of the type of deployment taking place:

Directory comparison — files are compared between the sending and receiving server at each tier in the deployment.

It is important that the file location at each next-tier target accurately reflect the target file location of the final targets, as no direct directory comparison between the originating source and final targets occurs. If the next-tier targets do not reflect the targets’ state, then files will be redeployed to the next-tier targets during the routed deployment. This will have the effect of restoring the next-tier targets to the same state as the target.

TeamSite comparison — files are compared between the two TeamSite areas on the originating source. The result of this comparison is generated into a file manifest whose files are deployed across the tiers as a file list deployment to their final targets. No further comparisons take place. The previous area in the TeamSite comparison must accurately reflect the contents of the target file locations of the final targets.

Payload or query-based — the payload or query-based file list is generated, and those files are compared to the next tier target files from the source. From that comparison, a new file manifest is generated, and those files are deployed across the tiers as a files list deployment. No further comparisons take place.

File list — the file list content is moved across the routed deployment to the final destinations. No comparison takes place.

Transactional

Routed deployments can be fully transactional. If a routed deployment that is configured as being transactional fails, the original content is restored in each participating target.

161


Manifest Information Stream Format Requirement

If the deployment type is a TeamSite comparison or query-based, the manifest deployment information stream format must be configured on the originating server and the first next-tier target. Refer to “Specifying the Deployment Information Stream Format” on page 125 in the OpenDeploy Installation Guide for more information.

Configuring Route Definitions

Route definitions are represented by the routeDefinition element in the nodes configuration file.

<nodeSet name="od_receiver_nodes"><node ../>...<routeDefinition name="routes">...

</routesDefinition></nodeSet>

The routeDefinition element contains a name attribute. This value is used in the deployment configuration to reference the particular set of route segments for a routed deployment. If you have multiple route definitions, each one must have a unique name.

You can configure as many route segments within a route definition as you need to complete the routed deployment. You can also configure multiple route definitions within the same nodes configuration file, as long as each one has a unique name.

A route definition’s name is specified in the routeDefinition element’s name attribute. For example:

<nodeSet name="od_receiver_nodes"><node ../>...<routeDefinition name="routeA">...

</routesDefinition><routeDefinition name="routeB">...



Routed Deployments

Configuring Route Segments

Each separate route segment contained within the route definition is represented by a nodeInfo element within the routeDefinition element. The nodeInfo element has the following associated attributes:

fromNode — specifies the logical name of the node that is the source of the route segment, for example:

fromNode="mars"

This logical name must match the localNode element’s name attribute in the sending server’s configuration file, for example:

<localNode name="mars" host="mars.mycompany.com" .../>

Refer to “Identifying the Host” on page 118 in the OpenDeploy Installation Guide for more information on configuring the localNode element in the OpenDeploy server configuration file.

toNode — specifies the logical name of the node that is the target of the route segment, for example:

toNode="venus"

This logical name must match one of the entries in the sending server’s nodes configuration file, for example:

<node name="venus" host="venus.mycompany.com" .../>

Refer to “Defining Target Nodes” on page 89 in the OpenDeploy Installation Guide for more information on configuring target nodes.

You must configure a nodeInfo element for each allowed route segment or that particular segment cannot be included in the routed deployment. Omitting a route segment requires the routed deployment to reach its targets through another route segment, or the routed deployment fails.

To configure the route segments listed in Figure 7, you would need to include the following in the nodes configuration file of mars:

<nodeSet ...><node .../>...<routeDefinition name="routes"><nodeInfo fromNode="mars" toNode="venus"/><nodeInfo fromNode="mars" toNode="jupiter"/><nodeInfo fromNode="mars" toNode="mercury"/><nodeInfo fromNode="jupiter" toNode="saturn"/><nodeInfo fromNode="jupiter" toNode="pluto"/>


You can specify a regular expression as the value for the toNode attribute. For example:

<nodeInfo fromNode="england" toNode="london.*"/>

163


Specifying Next-Tier File Locations

The nodes configuration file of the originating source must contain a nodes entry for each target that you want to receive deployed content. Those base server nodes that are to function as next-tier targets in a routed deployment must also have their file locations specified in their corresponding nodes entry. The content is deployed to that file location during the routed deployment. The location serves as the source file location for the movement of the content on to subsequent next-tier targets and end-targets.

The next-tier file location is specified by the targetArea attribute value in the server’s corresponding node element:

<nodeSet ...><node name="venus" ... targetArea="/tmp/dirA"/><node name="jupiter" ... targetArea="/tmp/dirA"/><node name="saturn" ... targetArea="/tmp/dirB"/><routeDefinition name="routes">...


In this example, if mars routed deployed content through the next-tier target venus, that content would be sent to the path /tmp/dirA on Venus.

The full path you specify for the targetArea attribute is unique to that target. You can specify the same location on all the next-tier targets, or give a different path to each one. The path syntax should reflect the operating system of that target host.

Configuring a Target as Both a Next-Tier and End Target

In some cases, you might want a next-tier target in a routed deployment to also be an end target for the deployed files. If so, you must include that target in the replication farm set for the deployment. Additionally, the file location on the next-tier target acts as the end target file location as well. You cannot have a separate target file location and a next-tier and end target file locations on the same target. The next-tier file location supersedes any other target file location specified in the deployment configuration.

Using Default Location Variables

In some cases you might want to avoid specifying a single file location on a next-tier target where multiple deployments from different sending servers might be received simultaneously. A series of default location variables are available for use in conjunction with the path you specify in the targetArea attribute. These variables generate subdirectories under the targetArea path where the deployed content can reside, away from potentially competing content being deployed simultaneously from other sources.


Routed Deployments

OpenDeploy supports the following default location variables to provide multiple file locations on the same receiving next-tier target:

{ORIGNODE} — the host name of the routed deployment’s originating source. For example, mars.

{ONODESRCDIR} — the source file location directory of the routed deployment’s originating source. For example, /website/files.

{ENODETARGDIR} — the target file location directory on the end targets. For example, /website/external/files.

{REPFARM} — the replication farm name contained in the routed deployment. For example, uk_sites.

Default location variables can be used in any number and any combination. The same variable can appear multiple times in the targetArea attribute value if you want. You must specify any delimiters, such as a slash (“/”), yourself. OpenDeploy does not automatically insert slashes between default location variables. If you include two variables together without a delimiter, those two values are combined into a single value.

In the following example, the originating source mars is performing a routed deployment, using venus as a next-tier target. The source file location of mars is /website/files. The target file location on the end targets is /website/external/files.

If the node element for venus was the following:

<node name="venus" ... targetArea="/tmp/dirA/{ORIGNODE}"/>

the file location on venus for the deployed content would be:

/tmp/dirA/mars

Similarly, if the node element for venus was the following:

<node name="venus" ... targetArea="/tmp/dirA/{ENODETARGDIR}"/>

the file location on venus for the deployed content would be:

/tmp/dirA/website/external/files

Combining both of these default location variables together without a slash delimiter between them merges the values together into a single term, for example:

<node name="venus" ... targetArea="/tmp/dirA/{ORIGNODE}{ENODETARGDIR}"/>

in which the file location would be:

/tmp/dirA/marswebsite/external/files

165


Including a slash between the variables:

<node name="venus" ... targetArea="/tmp/dirA/{ORIGNODE}/{ENODETARGDIR}"/>

results in an additional level in the path:

/tmp/dirA/mars/website/external/files

Referencing the Route Definition in the Deployment Configuration

A routed deployment is indicated in the deployment configuration by the presence of the routedDeployment element within the deploymentConfiguration element:

<deploymentConfiguration>...<routedDeployment ...>...

</routedDeployment></deploymentConfiguration>

The routedDeployment element contains the following attributes:

useRouteDefinition — specify the name of the routeDefinition element used for this routed deployment. The routeDefinition element is specified in the nodes configuration file. For example, if you wanted to use the route definition routes, which is already configured in the nodes configuration file of the source, the value would be:<routedDeployment useRouteDefinition="routes">

useRouteClass — specifies the user-defined router class implementation. For example:

useRouteClass="com.interwoven.od.adapter.route.firstmatch.

IWFirstMatchRouter"

transactional — indicate whether (yes) or not (no) the deployment configuration is transactional. Default value is no.

userServerNodeHost — indicate whether (yes) or not (no) the sending server’s local host value as specified in the server’s base server configuration file is to be included as the local host value in the generated deployment configuration. If this attribute is set to no, then the host name specified in the deployment configuration will be used. Default value is yes. See “Specifying a Common Host for Simplified Checking” on page 167 for more information on this feature.

You can only specify a single route definition in a routed deployment, so you must ensure that your route definition includes the route segments necessary to complete the deployment, including using regular expressions to reference the intermediate-tier base server’s configuration files if necessary.


Routed Deployments

Specifying a Common Host for Simplified Checking

Typically, when the deployment configuration at each tier in a routed deployment is generated, the host name of the sending server is included in the generated deployment configuration as the localNode element’s host attribute value. This value is then matched against the allowed host list present on each target node to determine whether the target will accept the deployed files. This requires that each target node have all the necessary source hosts listed in its allowed hosts list before the routed deployment can begin.

As an alternative, you can configure OpenDeploy to use the localHost element’s host attribute value contained in the initial deployment configuration, rather than the one in the sending server’s configuration file. This requires only the single host value to be listed in the allowed hosts list of each recipient node, making the management of allowed hosts at each of the servers much simpler.

You can enable this feature by configuring the routedDeployment element’s useServerNodeHost attribute with a value of no:

<routedDeployment ... useServerNodeHost="no">

The default value is yes. If you specify a value of yes, or omit the useServerNodeHost attribute from the configuration, the sending server’s logical name is used in the deployment.

Limitations

Routed deployments are not supported with the following types of deployments:

Those that contain multiple definitions.

Those that contain multiple source file locations.

Reverse deployments.

167


Reverse Deployments

A reverse deployment allows new or updated files residing on what is typically a target (often a production server) to be deployed back to the source (often a development server) that normally sends deployments. In this relationship, the reverse source deploys files to the reverse target. Unlike a typical forward deployment, the reverse source can only have the receiver software installed. The reverse target manages the reverse deployment, and the reverse source must be listed as a target node in the nodes configuration file of the reverse target. Reverse deployment files reside in the same directory as other deployments.

Reverse deployments are not supported for use with the multi-tiered or routed deployment features.

Reverse deployments are often used to deploy files generated on production servers back to the development server. For example:

Web server log files

Data files created via a CGI application

Assets uploaded through a Web server application

In Figure 9, the production server venus has generated files that need to be reverse deployed back to the development server mars. As the reverse target, mars initiates a reverse deployment from the reverse source venus. The deployment then takes place like any other deployment.

Figure 9: Reverse Deployment

mars(reverse target)

venus(reverse source)

OpenDeploy references a reverse deployment configuration.

Files are reverse deployed back to the reverse target.

Base server initiates reverse deployment to reverse source.


Reverse Deployments

Server Configuration

Each OpenDeploy reverse source and reverse target server in a reverse deployment must specify each other’s host as an allowed host. Refer to “Specifying Allowed Hosts for Received Deployments” on page 131 in the OpenDeploy Installation Guide for more information.

The reverse target’s server configuration (by default odbase.xml) must also specify the following items:

The reverse target host name must be listed as an allowed host, meaning the base server must list its own host in its server configuration file. Refer to “Specifying Allowed Hosts for Received Deployments” on page 131 in the OpenDeploy Installation Guide for more information.

The allowed directories that can receive the reverse deployment files must be specified. Refer to “Specifying Allowed Directories for Deployments” on page 133 in the OpenDeploy Installation Guide for more information.

Figure 10 shows the configuration requirements for the reverse target mars and the reverse source venus.

Figure 10: Server Configuration for Reverse Deployments

mars(reverse target)

venus(reverse source)

Allowed hosts: mars, venusAllowed directory for received files Allowed host: mars


Base server initiates reverse deployment to reverse source.

169


Deployment Configuration

Reverse deployments are configured in a manner similar to traditional deployments, except the source and target roles are switched as the reverse source and reverse target. The reverseSource and reverseTarget elements accommodate this change in roles.

The reverseSource element identifies the attributes regarding the sender of the deployment during a reverse deployment. The replicationFarmLink element specifies the target replication farm and its location to which the reverse source belongs. See “Target Replication Farms” on page 89 for more information on configuring target replication farms.

The reverseTarget element identifies the attributes regarding the recipient of the deployment during a reverse deployment.

<definition name="reverse_deployment"><reverseSource><sourceFilesystem area="C:\dev\website\files">

<pathSpecification><path name="monthly"/>

<pathSpecification></sourceFilesystem><replicationFarmLink>

<internal name="MYFARM"/></replicationFarmLink>

</reverseSource><reverseTarget><targetFilesystem area="D:\website\files"/>

</reverseTarget></definition>

Multi-Definition Deployments

You cannot include a definition containing a reverse deployment with other definitions containing forward deployments in the same deployment configuration.


Certified Limits for Number of Deployment Legs


A “leg” is considered the movement of a specific set of deployed files from a source file location to a target file location (definition element). You can compute the number of legs in a deployment by summing the number of node references used in all deployment tasks (execDeploymentTask elements) that will be executing simultaneously. Note that in this context a system deploying to itself uses two legs. See “Examples and Recommendations” on page 172 for details on how to determine the number of legs your deployment uses.

Refer to “Certified Limits for Number of Deployment Legs Table” on page 19 in the OpenDeploy Release Notes for a table containing the limits on a platform-specific basis. The rest of this section describes how the limits are determined.

Certification Factors

The following list describes the factors regarding the certification of deployment leg limits:

These measurements were recorded on systems where OpenDeploy was the main application running and there was no load on the system from other applications. Running OpenDeploy on a system where there are significant loads from other applications can affect these results due to available system resources such as memory and CPU cycles.

Limits are certified for a specific system and deployment configuration. Behavior of your deployments may vary depending upon system resource availability and deployment configuration.

The deployment used for certification testing was a directory comparison-based transactional deployment with each leg moving 30 or more files, each of which averaged 5 KB in size, spread over an average of 5 directories. The following features were not used in the tests:

Encryption

Deploy and Run scripts

Compression

Non-default comparison and transfer rules

Database deployments

Web services

All other deployment options are consistent with those included in the test.xml deployment configuration file, residing in the following location:


For OpenDeploy running on a Solaris host, the name server cache daemon (NSCD) was enabled.

171


Environmental Factors

The number of legs supported in your environment is dependent on many factors. The following environmental factors will have an impact:

On Solaris systems, the name server cache daemon (NSCD) must be enabled.

The memory usage for OpenDeploy increases as the total number of files and directories in the source and target file locations increases. This results from the need to keep track of information for all the files on the source and target.

File descriptors are consumed by OpenDeploy for writing to various log files.

Each Deploy and Run script consumes at least one file descriptor and potentially other system resources.

Examples and Recommendations

In a deployment containing the following target replication farms:

myFarm1 (containing four target node references)

myFarm2 (containing five target node references)

with the following definitions:

Definition myDefA (deploying to myFarm1)

Definition myDefB (deploying to myFarm2)

Definition myDefC (deploying to myFarm2)

and using the following deployment tasks:

<execDeploymentTask useDefinition="myDefA"/>

<execDeploymentTask useDefinition="myDefB"/>

<execDeploymentTask useDefinition="myDefC"/>

the total number of legs would be 14: (4 used by myDefA) + (5 used by myDefB) + (5 used by myDefC)



When creating a deployment configuration, consider whether your deployment involves multiple source-target directory pairings without Deploy and Run triggers per pair. If so, the best practice you should employ involves a multiple sub-source structure to conserve deployment legs. For example:

<definition><source><fileSystem>

<remoteDiff name="S1" area="/area1"><pathSpecification>

<path name="aaa"/><targetRules area="/targetarea1"/>

</pathSpecification></remoteDiff><remoteDiff name="S2" area="/area2"><pathSpecification>

<path name="bbb"/><targetRules area="/targetarea2"/>


</fileSystem></source><target><targetFilesystem area="__ignored__"/><replicationFarmLink>

<internal name="WEBSERVERS"/></replicationFarmLink>


Here the number of legs will be equal to the number of node references in the replication farm WEBSERVERS.

In some cases you can exceed the certified number of deployment legs on a UNIX host without incurring a significant performance loss by increasing the ulimit value. Refer to your operating system documentation for information on increasing the ulimit. Increasing available memory can also improve performance.

173


If the deployment structure requires Deploy and Run per directory pairing, you should use multiple definitions within the deployment configuration. With this approach you gain performance because the deployments execute in parallel, but this comes at the expense of consuming more legs. For example:

<definition name="def1"><source><fileSystem>

<remoteDiff area="/area1"><pathSpecification>

<path name="aaa"/></pathSpecification>


</source><target><targetFilesystem area="/targetarea1"/><replicationFarmLink>


</target></definition><definition name="def2">

<source><fileSystem>

<remoteDiff area="/area2"><pathSpecification>

<path name="bbb"/></pathSpecification>

</fileSystem></source><target><targetFilesystem area="/targetarea2"/><replicationFarmLink>



In this example, the number of legs is twice the number of node references in the replication farm WEBSERVERS. This is because there are two definitions that run in parallel.

If a deployment specifies a definition where the source and targets are the same host (for example, a “loopback” deployment), that deployment definition counts as two legs (a source leg and a target leg).


Chapter 4

Deployment Features

This chapter describes the following deployment features and how they are configured:

Filters

Comparison rules

Transfer rules

Permission rules

Use with access control lists (ACLs)

Deploying symbolic links

Parameter substitution

Deploying TeamSite extended attributes (EAs)

Use with adapters

Use with DataDeploy

Filters

You can modify the deployment configuration to include and exclude files and directories from the deployment through the use of filters. Filters refine the deployed content to only those items you want included. They can be used at the source of the deployment, one or more targets, or a combination of the two.

These filters can use one or both of the following criteria to determine whether to deploy an item or not:

File system path location and name

Naming pattern using regular expression

175

Deployment Features

Filters are applied differently depending on the deployment type. The following table describes how filters work on each type of deployment.

Deployment Type Filtering Action

Directory comparison Filters can be configured to be applied to either only the source-side, or to both the source-side and target-side.Source-side filters are applied to the source content resulting in a refined source image. Target-side filters are applied to the target content resulting in a refined target image.These two images are compared, and the result of the compare is deployed.The common configurations for directory comparison filters are:1. Identical filters are specified for both source-side and target-side, so that the source and target contents are identical. This configuration allows an exact copy of all the content that passes the filters on both sides, but it leaves everything else alone on the target.2. Only source-side filters are used, so that the target is a refined version of the source content. This configuration provides no protections to the target. If the DoDeletes feature is enabled, the target will become an exact mirror of the refined source content.

TeamSite comparison Filters are applied to the resulting list of paths produced from the TeamSite comparison of the area and previousArea file locations. The resulting filtered list is deployed.

File list Filters are applied to the list of relative paths in the file list. The resulting filtered list is deployed.

Payload adapter-based Filters are applied to the resulting list of paths produced from payload adapter. The resulting filtered list is deployed or expired in the target depend on the “action” type specified in the deployment configuration file.


Filters

Filter Placement

Filters are configured within the filters element throughout a deployment configuration. You have several options as to the placement of filters. The following sections describe the placement of filters within the configuration.

Source-Side Filters

Source-side filters can reside within the pathSpecification element. For example:

<source><fileSystem><remoteDiff area="C:\dev\website\files">

<pathSpecification><path name="."/><filters>

...</filters>...



Target-Side Filters

Target-side filters can reside in the following locations:

The targetRules child element of the source element:

<source><fileSystem><remoteDiff area="C:\dev\website\files">

<pathSpecification><path name="."/>...<targetRules>

<filters>...

</filters></targetRules>



The target element:

<target><targetFilesystem area="D:\website\files"/><filters>...

</filters></target>

177

Deployment Features

A targetRules element at the node level:<replicationFarmSet>

<replicationFarm name="MYREPLICATIONFARM"><nodeRef useNode="venus">

<targetRules><filters>

...</filters>

</targetRules></nodeRef>


Source-Side and Target-Side Filters Interaction

You can configure filters on the source side, target side, or both. How OpenDeploy uses filters depends on the source-target filter relationship:

If the filter exists only on the source side, OpenDeploy ignores those excluded source-side files and cannot deploy them. If the doDeletes feature is enabled, those excluded source-side files that are also present on the target-side will be deleted.

If the filter exists only on the target side, OpenDeploy assumes those excluded files do not exist on the target, and will deploy any files that also exist on the source-side.

If the filter exists both on the source and target sides, OpenDeploy ignores the excluded files on both sides, resulting in the target-side files being unaffected.

If you are using filters in conjunction with the doDeletes transfer rules feature, you must configure target-side exclusion filters to protect any files on the target that you do not want to delete. Otherwise, OpenDeploy will delete any files on the target that are not on the source, either because the files are physically not present in the source file location, or because source-side exclusion filters have made it appear that the files are not present. See “Transfer Rules” on page 190 for more information on configuring the doDeletes feature.

Override Precedence

Filters specified for the targetRules element within the pathSpecification element override any filters specified for the target element.

Filters specified for the targetRules element within the nodeRef element override any filters specified for the targetRules element within the pathSpecification element and any filters specified for the target element.


Filters

Inclusion Filters

Inclusion filters allow you to configure one or more criteria based on file system paths or naming patterns to filter only those files and directories you want included in the deployment. You can use multiple occurrences of either file system- or pattern-based inclusion filters, but you cannot combine both types in the same deployment configuration. You also cannot combine either type of inclusion filter with any type of exclusion or exception filter. See “Combining Filter Types” on page 185 for more information on filter compatibility.

If no inclusion filters are present, all files are included in the deployment, except any that are subsequently blocked from the deployment by exclusion filters. The use of exclusion filters is described later in this section.

File System-Based Inclusion Filters

File system-based inclusion filters permit those directories and files that match the specified path criteria to be deployed. Paths specified are relative to the source file location of the deployment, such as a file system directory or TeamSite edition.

File system-based inclusion filters are configured in the includePath element within the filters element:

<filters><includePath subPath="path_to_be_included"/>

</filters>

The includePath element’s subPath attribute specifies those paths and file names that represent the inclusion criteria. Those items to be deployed must meet that criteria in order to be included in the deployment. The path specified in the subPath attribute is relative to the local directory or TeamSite area containing the files to be filtered. This location is determined by both the area attribute, and any subdirectory specified in the pathSpecification element.

The following example shows a deployment that would only include the contents of the directory reports/monthly:

<filters><includePath subPath="reports/monthly"/>

</filters>

You can add inclusion paths to your deployment configuration file by adding another includePath element for each included path. For example:

<filters><includePath subPath="reports/monthly"/><includePath subPath="reports/quarterly"/>

</filters>

179

Deployment Features

When file system-based inclusion filters are present in the deployment configuration, an item needs only to match a single filter to be included.

File system-based inclusion filters are incompatible with pattern-based inclusion filters, as well as all exclusion and exception filters, in the same deployment configuration.

Pattern-Based Inclusion Filters

Pattern-based inclusion filters permit those directories and files that match the specified naming pattern to be deployed.

Inclusion filters are configured in the includePattern element within the filters element:

<filters><includePattern regex="pattern_to_be_included"/>

</filters>

The includePattern element’s regex attribute specifies the regular expression naming pattern against which the files and directories in a deployment are compared. Those items that match the naming pattern are included in the deployment. Those that do not are not included. See “Supported Regular Expressions” on page 186 for guidelines on OpenDeploy use and support of regular expressions.

The following example shows a deployment that would only include files with the extension .html:

<filters><includePattern regex=".*\.html$"/>

</filters>

You can specify multiple inclusion patterns for a deployment configuration file by adding another includePattern element for each pattern. For example:

<filters><includePattern regex=".*\.html$"/><includePattern regex=".*\.txt$"/>

</filters>

When composing your regular expressions, follow your operating system’s path separator syntax. For example, UNIX uses “/” while Windows uses “\\”. You can specify matches for a file on both Windows and UNIX operating systems by including [/\\] in your regular expression. This allows you to overcome the path separator syntax differences between Windows and UNIX. For example, to provide for a match of the file index.html on both Windows and UNIX file systems, you would configure it in the following way:

regex="[/\\]index\.html$"


Filters

When pattern-based inclusion filters are present in the deployment configuration, an item needs only to match a single filter to be included.

Pattern-based inclusion filters are incompatible with file system-based inclusion filters, as well as all exclusion and exception filters, in the same deployment configuration.

Exclusion Filters

Exclusion filters allow you to configure one or more criteria based on paths or naming patterns to filter out those files and directories you do not want included in the deployment. You can configure multiple exclusion filters of both file system- and pattern-based types in the same configuration. If only exclusion filters are in the configuration, items that meet the exclusion criteria are not deployed. If multiple exclusion filters are present, an item needs only to match a single one to be excluded. Exclusion filters are incompatible with inclusion filters. See “Combining Filter Types” on page 185 for more information on filter compatibility.

File System-Based Exclusion Filters

File system-based exclusion filters prevent those directories and files that match the specified path and name criteria from being deployed.

File system-based exclusion filters are specified by the excludePath element within the filters element:

<filters><excludePath subPath="path_to_be_excluded"/>

</filters>

The excludePath element’s subPath attribute specifies the file system location and name criteria against which the files and directories in a deployment are compared. Those items that match are excluded from the deployment. The path specified in the subPath attribute is relative to the local directory or TeamSite area containing the files to be filtered. This location is determined by both the area attribute, and any subdirectory specified in the pathSpecification element.

The following example shows a deployment that would exclude the directory WebFiles/working:

<excludePath subPath="WebFiles/working"/>

You can specify multiple exclusion paths for a deployment by adding another excludePath element for each excluded path. For example:

<filters><excludePath subPath="WebFiles/working"/><excludePath subPath="WebFiles/intranet"/>

</filters>

181

Deployment Features

Pattern-Based Exclusion Filters

Pattern-based exclusions filters prevent those directories and files that match the specified naming criteria from being deployed. Those items that do not match the exclusion criteria are deployed.

Pattern-based exclusion filters are specified by the excludePath element within the filters element:

<filters><excludePattern regex="pattern_to_be_excluded"/>

</filters>

The excludePattern element’s regex attribute specifies the regular expression naming pattern against which the files and directories in a deployment are compared. Those items that match are excluded from the deployment. See “Supported Regular Expressions” on page 186 for guidelines on OpenDeploy use and support of regular expressions.

For example, if you wanted to exclude any file whose name includes the extension .html, the excludePattern element value would be:

<excludePattern regex=".*\.html$"/>

You can specify multiple exclusion patterns for a deployment by adding another excludePattern element for each excluded pattern. For example:

<filters><excludePattern regex=".*\.html$"/><excludePattern regex=".*\.txt$"/>

</filters>

Exception Filters

In some cases, you might want to protect certain items or classes of items that would otherwise be excluded from the deployment by the presence of exclusion filters. For example, if you wanted to exclude any file whose name contains internal from the deployment, but still deploy the file internal.html, you would need to configure an exclusion filter for all files named internal, but also contain an exception for the file internal.html. File system- and pattern-based exclusion filters provide overrides to any and all exclusion filters present in the configuration.

Exception filters only work with the presence of exclusion filters in the deployment. You can use multiple occurrences of either file system- or pattern-based exception filters, but you cannot combine both types in the same deployment configuration. Exception filters are incompatible with any type of inclusion filter. See “Combining Filter Types” on page 185 for more information on filter compatibility.


Filters

File System-Based Exception Filters

File system location-based exception filters protect those directories and files that match the specified path and name criteria from being excluded from the deployment.

File system-based exception filters are specified by the exceptPath element within the filters element:

<filters><excludePath subPath="path_to_be_excluded"/>

<excludePattern regex="pattern_to_be_excluded"/><exceptPath subPath="path_to_be_excepted"/>

</filters>

The exceptPath element’s subPath attribute specifies the file system location and name criteria against which the files and directories in a deployment are compared. Those items that match are protected from exclusion filters. The path specified in the subPath attribute is relative to the local directory or TeamSite area containing the files to be filtered. This location is determined by both the area attribute, and any subdirectory specified in the pathSpecification element.


<filters><excludePattern regex=".*\.html$"/><exceptPath subPath="reports/monthly/index.html"/>

</filters>

Those files within the directory reports/monthly:

reports/monthly/reports.htmlreports/monthly/comments.html

are excluded from the deployment, but the file:

reports/monthly/index.html

is retained in the deployment because the exception filter overrides the exclusion filter.

File system-based exception filters can be used in any number, and with any combination of file system- and pattern-based exclusion filters. However, file system-based exception filters are incompatible with pattern-based exception filters.

183

Deployment Features

Pattern-Based Exception Filters

Pattern-based exclusions filters prevent those directories and files that match the specified naming criteria from being excluded from the deployment.

Pattern-based exception filters are specified by the exceptPattern element within the filters element:

<filters><excludePath subPath="path_to_be_excluded"/><excludePattern regex="pattern_to_be_excluded"/><exceptPattern regex="pattern_to_be_excepted"/>

</filters>

The exceptPattern element’s regex attribute specifies the regular expression naming pattern against which the files and directories in a deployment are compared. Those items that match are protected from exclusion filters. See “Supported Regular Expressions” on page 186 for guidelines on OpenDeploy use and support of regular expressions.

For example, if you wanted to protect any file whose name contains the extension .html from any exclusion filters in the deployment, the exceptPattern element value would be:

<exceptPattern regex=".*\.html$"/>


<filters><excludePath subPath="reports/monthly"/><exceptPattern regex="regex=".*\.html$"/>

</filters>

Those files within the directory reports/monthly:

reports/monthly/reports.docreports/monthly/reports.pdfreports/monthly/reports.txt

are excluded from the deployment, but the file:

reports/monthly/reports.html

is retained in the deployment because the exception filter overrides the exclusion filter.


Filters

Combining Filter Types

OpenDeploy employs the following rules for combining the different types of filters in a deployment configuration.

Inclusion Filters

File system-based and pattern-based inclusion filters are incompatible with each other, and with all other types of filters. A deployment can contain multiple occurrences of either type of inclusion filter, but no others.

Exclusion Filters

You can combine both file system- and pattern-based exclusion filters in any combination and number within the same deployment configuration.

Exclusion filters are incompatible with any type of inclusion filter.

You can combine exclusion filters with either file system- or pattern-based exception filters, but not both.

Exception Filters

You can use either file system or pattern-based exception filters, but not both, in a deployment configuration containing exclusion filters. File system and pattern-based exception filters are mutually exclusive to each other.

Exception filters are incompatible with any type of inclusion filter.

Specifying Path Syntax for Filters

When specifying a path for either file system- or pattern-based filters, use the path delimiter syntax for the host’s operating system (“\” for Windows, “/” for UNIX). If you are deploying to a mix of Windows and UNIX targets, the UNIX path delimiter syntax (“/”) will work for both Windows and UNIX targets.

185

Deployment Features

Supported Regular Expressions

OpenDeploy supports POSIX 1003.2 extended regular expressions (ERE), and makes use of Henry Spencer's NFA regex package. If you are not familiar with regular expressions, consult a reference manual such as Mastering Regular Expressions by Jeffrey Friedl.

When composing your regular expressions, follow your operating system’s path separator syntax. For example, UNIX uses “/” while Windows uses “\\”. You can specify matches for a file on both Windows and UNIX operating systems by including [/\\] in your regular expression. This allows you to overcome the path separator syntax differences between Windows and UNIX. For example, to provide for a match of the file index.html on both Windows and UNIX file systems, you would configure it in the following way:

regex="[/\\]index\.html$"

The following table summarizes supported regular expression characters and describes their functions:

Character Function

\ Indicates next character should not be interpreted literally if it normally is, and should be interpreted literally if it normally is not.

^ Matches beginning of line.$ Matches end of input or line.* Matches 0 or more instances of preceding character.+ Matches 1 or more instances of preceding character.? Matches 0 or 1 instances of preceding character.. Matches any single character.x|y Matches either x or y.{n} Matches exactly n instances of preceding character (where n is an integer).{n,} Matches at least n instances of preceding character (where n is an integer).{n,m} Matches at least n and at most m instances of preceding character (where n

and m are integers).[xyz] Matches any one of enclosed characters (specify range using hyphen, such as

[0-9].[^xyz] Matches any character not enclosed (specify range using hyphen, such as

[^0-9].\n Matches a line feed.\t Matches a tab.


Comparison Rules

Use of “^” Character

OpenDeploy compares the regular expression to the entire path, so using the “^” character to represent the beginning of the path is not recommended. The recommended syntax for finding any particular file or directory names is to use the slash or backslash “[/\\]” characters as the starting or ending delimiter.

Note that the pattern .* between two occurrences of the [/\\] character set will skip over slashes or backslashes in the between to match the largest number of items possible. One method to avoid this behavior this is to use [^/\\]* instead of .* so that it will not skip over slashes or backslashes.

Comparison Rules

Modification date is the primary comparison criterion used to determine whether or not a given file should be deployed.

If a source-side file’s modification date is newer than its target-side equivalent, then the file is deployed. You can also configure the deployment to deploy source-side files that have modification dates older than its target-side equivalent using the revert option, or if there is a difference in modification date either way using the dateDifferent option. These options are described later in this section.

If a source-side file’s modification date is identical to its target-side equivalent, then the following criteria are used in sequential order to determine whether or not a given file should be deployed:

Type mismatch (a file and a directory sharing the same name)

User difference (UNIX only)

Group difference (UNIX only)

Permission difference (UNIX only)

Access control list (ACL) difference (Windows only, disabled by default)

Size difference

Checksum difference (disabled by default)

If either the source-side’s or target-side’s, or both, host’s operating systems do not support a particular comparison criterion, that criterion is skipped.

You can customize some these criteria within a deployment configuration by setting various attributes within the comparisonRules element. Here is a listing of those attributes:

187

Deployment Features

dateDifferent — indicate whether (yes) or not (no) a file should be deployed if there is any difference in file date (older or newer) between the source and target versions. This differs from the OpenDeploy default date-based comparison setting, where a file is deployed only if the source file is newer than the target file. A value of yes indicates that the file should be deployed. Default value is no.

The dateDifferent attribute is mutually exclusive with the revert attribute. See “Date-Based Comparison Rules” on page 189 for more information.

The dateDifferent and checksumCompare elements are mutually exclusive. If both are configured, checksumCompare takes precedence and dateDifferent is ignored.

revert — indicate whether (yes) or not (no) a file should be deployed if the source version is older than the target version. A value of yes indicates that the file should be deployed. Default value is no.

The revert attribute is mutually exclusive with the dateDifferent attribute. See “Date-Based Comparison Rules” on page 189 for more information.

The revert attribute cannot be enabled if the checksumCompare attribute are also enabled.

ignoreAcls (Windows only) — indicate whether (yes) or not (no) to ignore differences in the ACLs during the file comparison. Default value is yes. See “Using OpenDeploy with ACLs” on page 198 for more information.

ignoreModes (UNIX only) — indicate whether (yes) or not (no) to ignore differences in the UNIX-based permission bit mask during the file comparison. Default value is no.

ignoreUser (UNIX only) — indicate whether (yes) or not (no) to ignore differences in the UNIX-based file user ownership during the file comparison. Default value is no.

ignoreGroup (UNIX only) — indicate whether (yes) or not (no) to ignore differences in the UNIX-based file group ownership during the file comparison. Default value is no.

checksumCompare — indicate whether (yes) or not (no) the checksum-based deployment feature is enabled. Using file differencing based on checksum can eliminate redundant file deployments that might otherwise arise from timestamp-based comparison, such as deploying only files associated with a software fix when an entire application has been re-compiled. Default value is no.

The cheksumCompare and dateDifferent elements are mutually exclusive. If both are configured, checksumCompare takes precedence and dateDifferent is ignored.

The checksumCompare attribute cannot be enabled if the revert attribute are also enabled.

You can enable and disable comparison rules in any combination. For example, in the following occurrence of the comparisonRules element:

<comparisonRules dateDifferent="yes" ignoreAcls="yes"/>

OpenDeploy applies the following rules:


Comparison Rules

A file will be considered for deployment if the source file modification date is either older or newer than the target file.

Differences in access control list (ACL) settings between the source are ignored during the comparison.

Otherwise, all other comparison criteria are in effect.

Access options specific to UNIX are ignored when deploying to a Windows target and access options specific to Windows are ignored when deploying to a UNIX target. Therefore, you will not receive any errors if you define both:

ignoreAcls="yes" andignoreUser="yes"

Date-Based Comparison Rules

You can configure your comparison rules to deploy files based on the following file modification date-based relationships:

Source file is newer than target file — no configuration necessary. This is the default deployment behavior when neither the dateDifferent nor revert attributes are configured. It is the equivalent of the following configurations:

dateDifferent="no" (revert is not present)

revert="no" (dateDifferent is not present)

dateDifferent="no" and revert="no"

Source file is older than target file — configure revert="yes".

Source file is newer or older than target file — configure dateDifferent="yes".

If both dateDifferent="yes" and revert="yes" are specified, the behavior is undefined.

189

Deployment Features

Transfer Rules

You can modify your deployment configuration to follow or ignore various file transfer-related rules through the transferRules element and its various attributes. Here is a listing of those attributes:

doDeletes — indicate whether (yes) or not (no) files and directories that reside in the target file location but not in the source file location should be deleted following the deployment. By default they are not. Default value is no.

There are special rules for using the doDeletes option with file list deployments. See “Using doDeletes with File List Deployments” on page 120 for more information.

This feature sometimes can cause inadvertent file deletions when used in conjunction with target-side filters. See “Source-Side and Target-Side Filters Interaction” on page 178 for more information.

dontDo — indicate whether (yes) or not (no) to proceed with the deployment following the comparison. If the value is yes, the deployment will not occur. Default value is no.

When you run a deployment with the dontDo option enabled, a directory is created on the target (assuming that directory does not already exist) as specified by the targetFilesystem element’s area attribute value. This occurs even though the dontDo option prevents the actual files themselves from being deployed.

Performing a deployment using this feature will log all simulated deployed files to the deployment log. This is a good tool to use to check and compare files without actually performing a deployment. Files that are logged as being deployed indicate a difference between what is on the source server and the target server. You can also enable this feature using the iwodcmd start -sim command-line tool, or the simulated deployment feature in the OpenDeploy user interface. See “Performing a Simulated Deployment” on page 59 for more information on the benefits of simulated deployments.

preserveAcls (Windows only) — indicate whether (yes) or not (no) to preserve the Windows access control lists (ACLs) when the files are moved. By default, OpenDeploy applies ACLs based on the ACLs already existing on the containing folders on the target receiving the deployed files. Default value is no. See “Using OpenDeploy with ACLs” on page 198 for more information.

The preserveAcls and setAccess attributes are mutually exclusive. Do not enable both in the same configuration. If both are enabled, the setAccess attribute is honored and preserveAcls attribute is ignored. See “Permission Rules” on page 193 for more information about the setAccess attribute.

The preserveAcls and changeAccess attributes are also mutually exclusive. Do not enable both in the same configuration. If both are enabled, the changeAccess attribute is honored and preserveAcls attribute is ignored. See “Permission Rules” on page 193 for more information about the changeAccess attribute.


Transfer Rules

svrTryCount (Windows only) — enter the number of times OpenDeploy will attempt to deploy the file to the target. This feature works in conjunction with Microsoft IIS, and is designed to accommodate times of heavy production server traffic.

svrTryInterval (Windows only) — enter the amount of time in seconds OpenDeploy waits between deployment attempts. This feature works in conjunction with Microsoft IIS, and is designed to accommodate times of heavy production server traffic.

svrTryDisableOverwrite (Windows only) — indicate whether (yes) or not (no) to disable the ability of OpenDeploy to deploy files to a server even if the svrTryCount and svrTryInterval elements are specified. This feature works in conjunction with Microsoft IIS, and is designed to accommodate times of heavy production server traffic. Default value is no.

rmReadOnly (Windows only) — indicate whether (yes) or not (no) you want a deployed file to be able to overwrite its read-only target equivalent. If this feature is enabled with a value of yes, OpenDeploy will remove the read-only attribute from the target file, allowing the deployment to occur. A value of no will prevent the overwriting. Default value is no.

compression — indicate whether (yes) or not (no) content is compressed prior to being deployed.

compressionLevel — indicate what level (0-9) of compression OpenDeploy uses if compression of deployed content is enabled. A value of 1 is the lowest level of compression, and 9 is the highest. A value of 0 provides no compression at all.

applySourceFileTime — indicates whether (yes) or not (no) the deployed file will retain its existing modification time. If the value is yes, the existing time is kept. If the value is no, then the time the file was written on the target host is used. The default value is yes.

Applying the source file time (applySourceFileTime="yes") to deployed files ensures that the timestamps of files on the target host match their counterparts on the source host. An advantage of this is that directory comparison deployments will only deploy files that have changed on the source, since the time stamps would no longer match those of the corresponding files on the target.

Applying the target system time (applySourceFileTime="no") is useful for situations where an application on the target system takes an action based on an updated time stamp. For example, a nightly process that looks for new files would only have to search for files with a time stamp within the past 24 hours, or an application server will know to refresh itself based on the updated timestamp on deployed files.

checksumVerify — indicate whether (yes) or not (no) checksum verification is being used to confirm the integrity of deployed files. This adds a measure of reliability to OpenDeploy’s guaranteed delivery protocol. Default value is no.

byteIncremental — indicate whether (yes) or not (no) the byte-level incremental deployment feature is enabled. Using this feature, only the incremental differences in changed files are deployed. Network bandwidth consumption is minimized when small updates are made to large files, such as application archive packages. This feature does not support executables. Default value is no.

191

Deployment Features

You can enable and disable transfer rules in any combination. For example, in the following occurrence of the transferRules element:

<transferRules doDeletes="yes" preserveAcls="yes"/>


Any files existing in the target file location but not in the corresponding source file location will be deleted following the deployment.

(Windows only) Access control list (ACL) information will be retained following the deployment.

Access options specific to UNIX are ignored when deploying to a Windows target and access options specific to Windows are ignored when deploying to a UNIX target.

Compression

You have the option of compressing content being deployed. Compression can reduce the size of the deployment, saving network bandwidth and deployment time between the source and targets. However, compression and associated decompression can require more CPU time or power.

Compression is configured in the compression and compressionLevel attributes of the transferRules element:

<transferRules...compression="yes"compressionLevel="6"/>

To enable compression in deployments, specify a value of yes for the compression element. The default value is no.

If you elect to use compression, you can select the level of compression, with 1 being the lowest and 9 the highest. A value of zero provides no compression at all, even if it is enabled in the compression element.

Whether to use compression or not, and to what level, depends on the system priorities within your enterprise. If bandwidth limitation is an issue, compression can be a valuable asset. If CPU power conservation is more important, compression may not be practical. The compression level should represent the best balance of these factors. A compression level of 6 is recommended for a typical enterprise. This is also the default level used if none is specified in the configuration.


Permission Rules

Permission Rules

You can modify your deployment configuration to follow or ignore various file permission-related rules through the permissionRules element and its various attributes. Here is a listing of those attributes:

amask (UNIX only) — enter the bit mask (in octal) to be ANDed with the permission bits of all files and directories. The amask octal value combines with the existing permission bit value of the affected file. If a file has the existing permission value of 664 (-rw-rw-r--) and the amask attribute as the following value:

amask="770"

then the resulting permission for that file (664 AND 770) following the deployment would be 660 (-rw-rw----).

omask (UNIX only) — enter the bit mask (in octal) to be ORed with the permission bits of all files and directories. The omask octal value combines with the existing permission bit value of the affected file. If a file has the existing permission value of 666 (-rw-rw-rw-) and the omask attribute as the following value:

omask="022"

then the resulting permission for that file (666 OR 022) following the deployment would be 644 (-rw-r--r--).

directory (UNIX only) — enter the permissions (in octal) given to all deployed directories. For example, if you wanted deployed directories to have the permission “drwxrwx---”, then the resulting value would be:

directory="770"

file (UNIX only) — enter the permissions (in octal) given to all deployed files. For example, if you wanted deployed files to have the permission “-rw-rw-r-x” , then the resulting value would be:

file="665"

group (UNIX only) — enter the group assigned to all deployed files and directories. This attribute value must be a valid group name or group ID. For example:

group="tech_pubs" or

group="200"

You must also specify the user attribute if you use the group attribute.

user (UNIX only) — enter the user who will own all deployed files and directories. This attribute value must be a valid user name or user ID. For example:

user="jdoe" or

user="105"

You must also specify the group attribute if you use the user attribute.

193

Deployment Features

changeAccess (Windows only) — enter a value that modifies the access control lists (ACLs) so that specified users have the designated rights. The new access control entry (ACE) for each specified user allows only the specified rights, discarding any existing ACE. In the following example:

changeAccess="{ jdoe:W, tech_pubs:NONE }"

any existing ACEs for jdoe and tech_pubs are removed, jdoe is granted write access, and the group tech_pubs has no access at all. Any other access rights that may have existed for other users are left unchanged. See “Using OpenDeploy with ACLs” on page 198 for more information.

The changeAccess and setAccess attributes are mutually exclusive. Do not enable both in the same configuration, or an error will occur.

The changeAccess and preserveAcls attributes are mutually exclusive. Do not enable both in the same configuration. If both are enabled, the changeAccess attribute is honored and preserveAcls attribute is ignored. See “Transfer Rules” on page 190 for more information about the preserveAcls attribute.

setAccess (Windows only) — enter a value that replaces the ACLs for the deployed files and directories. In the following example:

setAccess="{ jdoe:ALL, tech_pubs:RX }"

the existing ACL is removed and the user jdoe is granted full access. The group tech_pubs has read access to the specified files. Any other access rights that may have existed for the file are removed. See “Using OpenDeploy with ACLs” on page 198 for more information.

The setAccess and changeAccess attributes are mutually exclusive. Do not enable both in the same configuration, or an error will occur.

The setAccess and preserveAcls attributes are mutually exclusive. Do not enable both in the same configuration. If both are enabled, the setAccess attribute is honored and preserveAcls attribute is ignored. See “Transfer Rules” on page 190 for more information about the preserveAcls attribute.


<permissionRulesdirectory="770"file="664"group="marketing"user="rroe"/>


The deployed directories will have “drwxrwx---” access as indicated by the value 770.

The deployed files will have “-rw-rw-r--” access as indicated by the value 664.

All deployed directories and files are assigned to the group marketing.

All deployed directories and files are owned by the user rroe.


Permission Rules

Cross-Platform Deployments

Typically, those permission rules specific to UNIX are ignored when deploying to a Windows target and permission rules specific to Windows are ignored when deploying to a UNIX target. However, during a directory comparison deployment initiated by a Windows source (or reverse source for reverse deployments) to a UNIX target, files on the sending host are regarded as having those UNIX-specific permission rule identities present in the deployment configuration during the compare phase of the deployment, even though those attributes are not supported by the sending host’s Windows operating system.

For example, if a Windows source deploys files to a UNIX target, and the deployment configuration specifies values for the group and user attributes, those files would assume those UNIX-based identities during the comparison of the source and target files.

This behavior only applies when deploying from a Windows source to UNIX targets using the directory comparison method. UNIX sources cannot apply Windows-specific permission rules to content when deploying to Windows hosts.

User and Group Ownership Transferal

You can switch UNIX-based user and group ownership of deployed files and directories as an option of the file permission rules. For example, upon deployment you might want to change the ownership of a set of files currently owned by the user jdoe to the user rroe. Similarly, you might want to change the group ownership from tech_pubs on the source to the group marketing at the target.

This feature is defined for user and groups by the userTranslation and groupTranslation elements, respectively. Both of these elements are child elements of the permissionRules element. The permissionRules element must first be specified before using these two elements. Each element has the following attributes:

from — enter the existing source user or group ID (or the numerical uid or gid value assigned to a particular user or group account on the UNIX source). For example:

from="jdoe" or

from="105"

to — enter the new target user or group ID. For example:

to="rroe" or

to="110"

195

Deployment Features

You must determine the appropriate user and group IDs at both the source and targets before you modify these attributes. You can determine these by using the id command at the prompt on a UNIX host. Your server will respond by displaying your user ID (UID) and group ID (GID). Enter the following command on your UNIX prompt for more details regarding the usage of this command:

man id


<permissionRules><userTranslation from="jdoe" to="rroe"/><groupTranslation from="100" to="200"/>

</permissionRules>

OpenDeploy will review the files in a deployment for those owned by user ID jdoe or group ID 100, and assign those files a new user ownership of rroe and group ownership of 200 after they are deployed to the target.

Setting the File Transport Buffer Size (Bandwidth Throttling)

You can set a default buffer size in bytes for transporting files from your OpenDeploy source server, allowing you to “throttle” the bandwidth consumption on a per-deployment basis. This amount is specified in the transportProperties element’s bufferSize attribute. For example:

<deploymentConfiguration>...<transportProperties name="od" bufferSize="8000"/>...


The transportProperties element also contains the name attribute. This attribute must be included in the deployment configuration, but can only have the value of od.

The file transport buffer size settings in the deployment configuration take precedence over the equivalent settings in the source server’s base server configuration file. If you do not specify the buffer size in the deployment configuration, then any setting in the base server configuration file takes precedence.

The file transport buffer size specified in the deployment configuration does not apply to the target’s buffer size. That value is specified in the target’s server configuration.


Setting the File Transport Buffer Size (Bandwidth Throttling)

Calculating Optimum Buffer Size

You can calculate the optimum buffer size for your network environment using the following formula:

buffer size = (nominal bandwidth) * (round trip delay)

Run the ping command from the command prompt to determine the round trip delay from your sender to receiver.

If you set your OpenDeploy transport buffer size to a larger value than your network can accommodate, you might experience performance degradation.

The following table illustrates the transfer rate associated with different buffer sizes during a deployment of 20 MB of content on a network with nominal bandwidth of 100 KB/second:

These rates are based on deployments where the sending and target servers are on separate hosts within the network. Loopback deployments (deployments where the sender deploys to itself) are not reflective of these rates.

Sender Buffer Size (Bytes) Target Buffer Size (Bytes) Average Transfer Rate (Kilobytes Per Second)

8000 8000 4845555 45555 88262144 262144 3645555 262144 69

197

Deployment Features

Using OpenDeploy with ACLs

Access Control Lists (ACLs) on Windows servers have the following syntax:

{ name:ACE, name:ACE, ... }

where name is the ACL name and ACE is the Access Control Entry (ACE) type.

ACL Names

The ACL name can be one of the following:

User name

Group name

Domain name\user name

Domain name\group name

ACE Types

ACEs consist of either of the following:

Perm bits

Standard perms

Perm Bits

Perm bits are sequences made up of one or more of the following characters:

R — read

W — write

X — execute

D — delete

P — change permissions

O — take ownership; equivalent to RWX


Using OpenDeploy with ACLs

Standard Perms

Standard perms consists of one of the following:

ALL — RWXDPO

NONE — none

READ — RX

WRITE — W

CHANGE — RWXD


setAccess={ andre:ALL, everyone:RX }

OpenDeploy would remove the existing ACL and grant the user andre full access and the group everyone read access to the specified files.


changeAccess={ chris:ALL, everyone:RX }

would remove any existing ACEs for chris and everyone, and grant chris full access and the group everyone read access to the specified files. Any other existing ACEs would remain unchanged.

Ignoring and Preserving ACLs

The following table describes what OpenDeploy does when the comparisonRules element’s ignoreAcls attribute interacts with the transferRules element’s preserveAcls attribute.

See “Comparison Rules” on page 187 for more information on configuring the ignoreAcls attribute, and “Transfer Rules” on page 190 for more information on configuring the preserveACLs attribute.

preserveAcls="no" preserveAcls="yes"

ignoreAcls="no" Deployment includes ACLs for comparison but does not deploy the ACLs.

Deployment includes ACLs for comparison and does deploy the ACLs.

ignoreAcls="yes" Deployment does not include ACLs for comparison and does not deploy ACLs.

Deployment does not include ACLs for comparison but does deploy the ACLs.

199

Deployment Features

Enabling UNIX-Based Deployments When Extended ACLs Are Present

Deployments running on UNIX hosts where extended ACLs are present (DFS, AFS, and so forth) might fail. When deploying files between OpenDeploy UNIX hosts, OpenDeploy attempts, by default, to replicate the ACLs from the source to the target. Imposing specific user-group ownerships is done through the permissionRules element’s user and group attributes.

On some UNIX file systems, the OpenDeploy process may be prevented from setting ACLs on deployed files and directories, which causes the deployments to fail.This is caused by extended security mechanisms introduced by file systems such as AFS and DFS.

In response to this limitation, OpenDeploy supports skipping the set ACL operations. With this functionality, the deployed items take on the ownership of the running OpenDeploy process.

To use the enhanced functionality, configure the permissionRules element in the deployment configuration in the following manner:

<permissionRules user="_iwod_user_" group="_iwod_group_"/>

Note: "_iwod_user_" and group="_iwod_group_" are the literal values, not variables.

When the OpenDeploy server sees these special keywords, the set ACLs operations will be skipped. For example:

<target><comparisonRules dateDifferent="yes"/><permissionRules user="_iwod_user_" group="_iwod_group_"/><targetFilesystem area="/tmp/deploydir"/><replicationFarmLink>

<internal name="MYFARMNAME"/></replicationFarmLink>

</target>

This causes OpenDeploy to deploy files to the target on the receiver if the date is different between sender file and receiver file, and not apply the original ownership to the deployed items. The deployed items have ownership of the OpenDeploy process.


Deploying Symbolic Links

Deploying Symbolic Links

By default, a symbolic link will be transferred intact and will point to the same relative or absolute path on the target side that it was pointing to on the source side. OpenDeploy will not deploy the actual file itself, nor will it validate the link on the target side to ensure the pointed-to files reside on the target. However, you can elect to have OpenDeploy deploy the actual pointed-to files by enabling the follow links feature. This feature is not available with OpenDeploy running on Windows.

In the following example, foo is a link that points to the file /etc/reports.txt. If you enter the following command at the prompt:

ls -l foo

the return would be

foo -> /etc/reports.txt

If foo is moved as part of a deployment with the follow links feature enabled at the source side, the deployment would find the file /etc/reports.txt and deploy it to the target as a new version of foo, replacing the one already there. This feature is useful if the source file location contains links, but the files they point to reside outside of the area and would otherwise not be included in the deployment.

If you want to move the items pointed to by links contained on the source file location, you can enable the follow links feature with the followLinks attribute of the sourceTransferRules element. For example:

<sourceTransferRules followLinks="yes"/>

201

Deployment Features

The following table shows the results of deploying symbolic links from the source. The FollowLinks Enabled column refers to whether the sourceTransferRules element’s followLinks attribute is enabled (followLinks="yes") or not (followLinks="no"). The Matching Target Contents column refers to the presence of a link, file, or directory present in the target file location that has the same name as the symbolic link being deployed.

FollowLinksEnabled?

Matching Target Contents

Result

no none The symbolic link is deployed to the target.

no link, file, or directory

The existing item is replaced by the symbolic link with the same name.

yes none The symbolic link is traversed and the file or directory it points to is deployed. The item traversed to cannot be another symbolic link. It must be a file or directory. Traversing multiple links is not supported.

yes link, file, or directory

The symbolic link is traversed and replaces any existing link, file, or directory on the target. The item traversed to cannot be another symbolic link. It must be a file or directory. Traversing multiple links is not supported.


Parameter Substitution


Parameter substitution is a feature that allows you to specify attribute values as parameters whose values you can specify on a deployment-specific basis when running a deployment. You can configure any attribute value in a deployment or XML-based adapter configuration file for parameter substitution. Each time you start a deployment, you indicate the value of each attribute configured for parameter substitution as a parameter=value pair. Different instances of the same deployment can have different attribute values. The parameter substitution feature turns a deployment configuration file into a template that you can customize each time you run it.

To use parameter substitution, you must determine which attributes to specify as parameters, and modify them in the appropriate configuration. Parameters use the following syntax:

$parameter^[default_value]

where parameter is some value you will specify in conjunction with the iwodcmd start command-line tool, and default_value is the value used if no parameter is specified. Default values are described in “Use with Deployment Instances” on page 206.

For example, if you wanted to designate the area attribute of the remoteDiff element of a particular deployment configuration as parameter srcarea, you would give that attribute the following value:

area="$srcarea^"

Every parameter entered into the configuration file must include the dollar sign (“$”) at the beginning and the carat (“^”) at the end. Otherwise, you are free to name a parameter anything you want (other than the parameter iwdd, which is reserved for performing a deployment of a DataDeploy configuration).

If you have a parameter or default value in the file that includes the “$” character, you must add an additional “$” character to distinguish this value from the parameter substitution syntax. For example, the following example would fail:

value="$abcd^[my$val]"

Instead, the example should be updated as:

value="$abcd^[my$$val]"

If a configuration includes a parameter, but no value is specified when the deployment is run, the deployment may fail.

Parameter names cannot begin with the string __iwod. This string is reserved for OpenDeploy internal use.

203

Deployment Features

Default Values

You can apply default values to parameter substitution using the following syntax:

$parameter^[default_value]

where default_value is the parameter value the deployment uses if no value is specified at the time of invocation. For example, if you had the following configuration:

srcarea="$srcarea^[C:\Temp]"

and then invoked the deployment test using the following command:

iwodcmd start test -k srcarea=C:\files

then the parameter substitution would specify the srcarea value as “C:\files”.

However, if you ran the deployment without the parameter=value for the srcarea attribute:

iwodcmd start test

then the default srcarea attribute value (C:\Temp) would be used.

Use of the parameter default value in the configuration is optional. However, if you configure a parameter in your configuration file that does not include a default value, and you do not specify a parameter value when running the deployment, the deployment may fail.

Running Deployments with Parameter Substitution

The following sections describe how to specify parameter substitution values when running deployments.

User Interface

When you are running deployments from the browser-based user interface, you can specify your parameter substitution parameter=value pairs in the Start a Deployment window’s Parameters box (Figure 1).

Figure 1: Parameter Substitution in the User Interface



If either the parameter or its assigned value contained a space, for example:

srcarea=C:\Program Files\monthly

it is not necessary to enclose the parameter in quotations. Note that this is different from running from the command-line (see below).

If you are specifying multiple parameters, separate each parameter=value pair with a comma (“,“), for example:

srcarea=C:\temp,tgtarea=C:\western\files

See “Starting a Deployment” on page 56 for more information about starting deployments from the user interface.

Command-Line

You can run the deployment from the command line using the iwodcmd start command-line tool. The syntax for using iwodcmd start with parameters is:

iwodcmd [-odinst instName] start deployment -k parameter=value

For example, if you wanted to apply the value C:\temp to the parameter srcarea in the deployment configuration file test, you would enter the following command at the prompt:

iwodcmd start test -k srcarea=C:\temp

If either the parameter or its assigned value contained a space, then the entire combined parameter and value must be placed inside of quotation marks. For example, if the value of srcarea is:

C:\Program Files\monthly

then you would enter:

iwodcmd start test -k "srcarea=C:\Program Files\monthly"

Multiple -k key=value pairs may exist on the command line, for example:

iwodcmd start test -k src=/mysource -k trg=/mytarget

The iwodcmd start command can only be issued on the host where the OpenDeploy server is installed. This command can be issued by anyone regardless of whether they hold an Administrator or User role. There are no authentication or authorization checks on individuals issuing command-line tools.

See “Running Deployments from the Command Line” on page 67 for more information on that iwodcmd start command.

205

Deployment Features

Use with Deployment Instances

One usage of parameter substitution is to combine this feature with specific instances of a deployment. That way, you can run multiple instances of the same deployment configuration file, but use parameter substitution to make modifications in each instance. See “Specifying a Deployment Instance” on page 69 for more information on this feature.

In the following example, there are two instances of the deployment reports being run using parameter substitution.

iwodcmd start reports -inst monthly -k "srcarea=C:\Program Files\monthly"

iwodcmd start reports -inst quarterly -k "srcarea=C:\Program Files\quarterly"

In the first instance monthly, the source file area is specified as C:\Program Files\monthly using parameter substitution. In the second instanced quarterly, the source file area is specified as C:\Program Files\quarterly.

You can specify an instance of the deployment in the user interface (Figure 2) by entering the instance name in the Instance Name box directly above the Parameters box:

Figure 2: Specifying the Deployment Instance with Parameter Substitution

Use with Scheduled Deployments

You can also apply parameter substitution to scheduled deployments. See “Applying Parameter Substitution to Scheduled Deployments” on page 244 for more information.

Use with Adapters

You can use parameter substitution with adapters in a manner similar to deployment configurations, including the use of default values. Only XML-based adapter configurations can include parameter substitution. Those configurations that are not XML-based, such as the FTP and email adapters, cannot use parameter substitution.



Parameter Namespaces

As an option, you can specify the parameter namespace for use in parameter substitution. The parameter name is prepended with the namespace to get a fully-qualified parameter name. The fully-qualified parameter name is used to look up substitution values available in the closest scope. If no parameter namespace is specified, the parameter is considered to be in the global namespace.

The parameter namespace is delineated into sub-scopes by a period (“.”). For example, a parameter namespace value of “a.b” specifies a subordinate namespace “b” of the encompassing namespace “a”. The parameter namespace “a” in turn is a subordinate namespace of the global namespace.

When OpenDeploy substitutes a parameter, it takes the parameter value from the closest namespace in which the parameter lies. For example, when substituting $test in a configuration where the namespace is specified as a.b, test is first searched in the namespace a.b (a.b.test). If no value is found for a.b.test, OpenDeploy searches in the next higher namespace a, looking up value for a.test. If that is also not available, OpenDeploy moves up to the global namespace and looks up value for test. Failing that, it uses the default value of test if it is specified. Finally, in the absence of a default value, $test is simply replaced with an empty string.

The search for parameter value begins in the namespace of the parameter and progressively moves upwards to the wider namespaces until the global namespace is reached. Namespaces that are subordinate to the namespace of the parameter are never searched.

You can specify the parameter namespace for a configuration using the optional parameterNS attribute. This attribute is associated with different elements depending on the type of configuration:

Deployments — deploymentConfiguration

Delivery adapters — odAdapter

Payload adapters — custom

For example:

<deploymentConfiguration parameterNS="a.b">

The parameter namespace of each configuration is independent of others. However, you can build a relationships between configurations using appropriate namespace values, such as using namespace values that are related by being under the same scope.

Fully qualified parameter names that begin with the string __iwod are not supported, since __iwod is reserved by OpenDeploy for internal use.

207

Deployment Features

Utilizing the Delivery Adapter Framework

The Delivery Adapter Framework enables the creation of application-specific delivery adapters for extending the content delivery capabilities of OpenDeploy. This allows you to extend the reach of your content distribution network to specialized devices and protocols, such as edge or cache servers.

The Delivery Adapter Framework allows the referencing of a user-created Java callout in the deployment configuration. After content is deployed to a target running the base server or receiver software, the Java class that implements the delivery adapter is invoked with a manifest of files and any other adapter properties that are specified in the deployment configuration.

When the adapter is invoked after the content is received, it has a handle to the manifest file (which lists the items deployed or deleted on the target side). The adapter can walk through the manifest to perform whatever operations are deemed appropriate by the developer of the adapter. Adapter developers can parse through the manifest file and take the necessary action based on their requirement.

An example of a delivery adapter is provided in the following location:

od-home/adapters/example

Note: Use of delivery adapters with EasyDeploy is not supported.



How Delivery Adapters are Incorporated into Deployments

Delivery adapters are invoked on the target side after the deployment. Adapters cannot be invoked on the source side. Depending on your needs, you can configure your deployment to deploy content to an OpenDeploy server on another host, or to deploy files back to the sending server host, known as a loopback deployment.

Figure 3 shows how a delivery adapter is incorporated into a regular deployment between separate hosts. When the content is deployed from the sender mars to the target venus, the delivery adapter on venus takes the deployed content and moves it to jupiter, which does not have an OpenDeploy server.

Figure 3: Delivery Adapter Using Regular Deployment

Figure 4 shows how a delivery adapter is incorporated into a loopback deployment. The sender mars performs a deployment to itself. The source and target file locations must be different. After the deployment is complete, the delivery adapter on mars takes the deployed content and moves it to jupiter, which does not have an OpenDeploy server.

Figure 4: Delivery Adapter Using Loopback Deployment

mars venus jupiter

delivery adapter

source file location target file location delivery adapter target

delivery adapter

mars jupiter

source file location target file location delivery adapter target

209

Deployment Features

Configuring Delivery Adapters

Delivery adapters are configured in the deployment configuration using the odAdapterSet element, which resides within the target element.

<target>...<odAdapterSet>...

</odAdapterSet></target>

The odAdapterSet element is a container for odAdapter elements. You must configure a separate odAdapter element for each delivery adapter you are using in the deployment.

The odAdapter element contains the following attributes:

name — (optional) specify the unique name of the adapter being used, for example:

name="MyAdapter"

class — specify the name of the Java class that implements the adapter. For example:name="com.interwoven.od.adapter.delivery.ftpadapter.IWftpAdapter"

parameterNS — specify the parameter namespace for use in parameter substitution. See “Parameter Namespaces” on page 207 for more information.

parameter — specify the parameter string for the adapter. The developer of the adapter is responsible for defining the meaning and syntax of the parameter string. This value can be a Java class, or the full path to a configuration file that includes the necessary parameters, for example:

parameter="xyz" or

parameter="config_file_path"

The parameter attribute value typically contains the destination of the deployed files.

If there are no associated parameters for the specified Java class, you can give the parameter attribute a null value. For example:parameter=""

async — indicates whether (yes) or not (no) the adapter is asynchronous. If it is asynchronous (async="yes"), then the adapter cannot be transactional. If it is not (async="no") , then the adapter can be transactional, as long as the adapter itself is written to include the transactional feature. Default value is yes.

logLevel — (optional) indicate one of the following logging levels (consistent with log4j standards):

DEBUG — specifies fine-grained informational events that are most useful to debug an application.

INFO — specifies informational messages that highlight the progress of the application at a coarse-grained level. This is the default value.

WARN — specifies potentially harmful situations.



ERROR — specifies error events that might still allow the application to continue running.

FATAL — specifies very severe error events that will presumably lead the application to abort.

Specifying Targets

When you use delivery adapters in a deployment, the delivery adapter is responsible for specifying the target file location of the deployed content. Each delivery adapter that is included with OpenDeploy typically includes an associated configuration file that specifies the target location. The path to this configuration file is referenced by the parameter attribute.

Deploying to Multiple Targets

You can use delivery adapters to deploy to multiple targets. For each target to which you want to deploy content using a delivery adapter, configure a separate odAdapter element.

In the following example, the FTP delivery adapter is used to deploy files to two different targets:

<odAdapterSet><odAdapter class="com.interwoven.od.adapter.delivery.ftpadapter.

IWftpAdapter" parameter="ftpconfig_path1" async="yes"logLevel="INFO"/>

<odAdapter class="com.interwoven.od.adapter.delivery.ftpadapter.IWftpAdapter" parameter="ftpconfig_path2" async="yes" logLevel="INFO"/>

</odAdapterSet>

The class attribute contains the same value. However, the parameter attribute value references different FTP configuration files (ftpconfig_path1 and ftpconfig_path2), each of which includes a different target.

Target locations are configured differently in each adapter’s configuration file depending on the type of delivery adapter being used. See Appendix A, “Delivery Adapters” on page 439 for your particular delivery adapter.

Writing Delivery Adapters

The following instructions are included to assist you in writing your own Java adapters for use in the Delivery Adapter Framework.

To write a Java adapter, follow these steps:

1. Add baseadapter.jar to your classpath. This jar file contains the base implementation of the adapter.

Your class should be derived from IWODDeliveryAdapter (contained in basedadapter.jar) and it should implement the following methods:

211

Deployment Features

A constructor that has no parameters, for example: public AdapterExample().

A deploy method taking no parameters: deploy(). The method signature would be: public boolean deploy().

The deploy method return value indicates the success or failure of the deployment:

• True — the adapter deployment was successful.

• False — the adapter deployment failed. If the failed adapter deployment is transactional and synchronous (async="no"), then the deployment is rolled back to its previous state.

A rollback method if you want the delivery adapter to be transactional: rollback(). The method signature would be: public boolean rollback().

The rollback method return value indicates the success or failure of the rollback of the adapter:

• True — rollback of the adapter deployment was successful.

• False — rollback of the adapter deployment failed.

2. Add your own adapter implementation in your new class and compile it into a class file.

3. Package your Java class files into a .jar file, and place it in the following directory:


4. Add the odAdapter element in your deployment configuration file. Supply your class (which is derived from IWODDeliveryAdapter) as the class attribute value of this odAdapter element, for example:

<odAdapterSet><odAdapter class="com.interwoven.od.adapter.delivery.example"parameter="" async="yes" logLevel="INFO"/>

</odAdapterSet>

See “Configuring Delivery Adapters” on page 210 for more information.

5. Restart the OpenDeploy server instance. The adapter implementation is available upon restart.

6. Start the deployment. The adapter implementation is invoked after the deployment. The files and configuration instructions to use the Delivery Adapter Framework for spe-cific adapters are included and described in Appendix A, “Delivery Adapters” on page 439.

JDK Requirement

If you intend to create your own delivery adapters, you must install the appropriate Java Development Kit (JDK). Refer to “JDK” on page 24 in the OpenDeploy Release Notes for the supported versions of the JDK.

This JDK installation requirement does not apply to delivery adapters included with OpenDeploy, as the required Java run-time environment (JRE) is already included.



Sample Delivery Adapter

OpenDeploy provides a sample delivery adapter that generates a log file that contains all the manifest information about the directories and files that are deployed or deleted when the deployment is run. This sample adapter is intended to illustrate how you can implement your own adapters within the Delivery Adapter Framework. The required Java code for use with this sample adapter resides in your host at the following location:

od-home/adapters/delivery/example/AdapterExample.java

To incorporate this functionality into your deployment, add the following code to the deployment configuration within the target element:

<odAdapterSet><odAdapter class="AdapterExample" parameter=""/>

</odAdapterSet>

When the deployment is run, the information on the deployed content is written to the following file:

od-home/(od-instance)/log/hostname_adapter.log

where hostname is the name of the source host. For example, mars_adapter.log.

The contents of the manifest log file are based on the structure specified in the internal manifest DTD file. You can access this DTD at:

od-home/dtd/conf/odmanifest.dtd

Refer to Chapter 17, “OpenDeploy Manifest DTD” on page 269 in the OpenDeploy Reference for more information on the internal manifest DTD.

Logging

Delivery adapters have their own log files. See “Adapter Logging” on page 269 for more information.

213

Deployment Features

DataDeploy

OpenDeploy can deploy database assets in a variety of ways using the DataDeploy module. The DataDeploy module must be licensed on the sending base server. Refer to “Add-On Module Licensing” on page 152 in the OpenDeploy Installation Guide for more information.

DataDeploy deploys structured XML files, such as TeamSite data content records (DCRs) and extended attributes (EAs), to databases residing on the

Deploy database assets to an OpenDeploy receiver, either alone or in conjunction with the deployment of associated files.

Deploy database assets directly to a database.

Deploy TeamSite EAs and DCRs assets to a database using database auto-synchronization (DAS).

Enabling DataDeploy on the Source Base Server

After installing and licensing the DataDeploy module, you must enable and configure it in the databaseDeployment element in the source base server configuration file (by default odbase.xml). Refer to “Database Deployments” on page 146 in the OpenDeploy Installation Guide for more information.

Database Deployment in the Deployment Configuration

Database deployment configuration is described in Chapter 5, “DataDeploy Deployments” on page 111 in the Database Deployment for OpenDeploy Administration Guide. This manual also contains detailed information on configuration files and databases used in database deployments. You should familiarize yourself with this information prior to configuring and running database deployments.


Chapter 5

Deploy and Run

The Deploy and Run feature allows you to configure OpenDeploy to execute an external script at a specified stage of the deployment. This stage can be the deployment of a particular type or class of file or directory, or even the success of the deployment itself. Using Deploy and Run, you can configure OpenDeploy to do the following tasks automatically:

Execute a notification script upon a failed deployment

Run a language-checking script during deployment

Alert you each time an executable file (with a file extension of .exe) is deployed

OpenDeploy supports any scripting language. The script must reside on the server where it is to be invoked. OpenDeploy will not transfer that script.

Note: Deploy and Run scripts cannot be triggered by simulated deployments. See “Performing a Simulated Deployment” on page 59 for more information on this feature.

Requirements

Deploy and Run requires the following components:

The presence of a customized script to be run.

A directive indicating in what situation the script should be invoked:

Deployment of a specific file or filenames matching a certain pattern

Deployment [creation] of a specific directory

Before or after the actual deployment.

On the source or target side of the deployment

On success or failure of the deployment, or always

Not all of these options are applicable in combination with one another.

215

Deploy and Run

Interacting with the Windows Desktop

If you are using a Deploy and Run script on a Windows host that writes to the console, you must enable the base server or receiver service that launches the script to interact with the Windows desktop. If you are not running scripts that write to the console, this configuration is not necessary.

To configure Deploy and Run to interact with the Windows desktop, follow these steps:


2. Right-click on the Interwoven OpenDeploy Service and select Properties from the pop-up menu to open the Properties window.

3. Click the Log On tab to make it active.

4. Check the Allow the service to interact with desktop option to enable that feature.

5. Click OK.

Triggers

You can configure Deploy and Run scripts to be triggered on a total deployment basis (macrodeploy), or by specific task events (microdeploy) that occur in the course of the deployment, such as a connection with a particular target. Where within this cycle you want to add Deploy and Run scripts determines how Deploy and Run is configured.

Figure 1 shows the sequence of those deployment- and task-level steps where you can set Deploy and Run scripts.

Figure 1: Deploy and Run Stages in the Deployment

end of deployment

beginning of deployment

deployment-level basis (macrodeploy)

task-level basis (microdeploy)

before connection

after connection/before compare

after compare/before transfer

after disconnection

after transfer/before disconnection

after deploymentbefore deploymentafter rollback


Triggers

Deployment-Level Triggers

Deployment-level, or macrodeploy, triggers are associated with the entire deployment as a single entity. They can be configured to occur either at the beginning of a deployment before the connection between the source and targets occurs, or following the completion or termination of a deployment at the time of host disconnection. They also can be configured to trigger if the deployment is successful, a failure, or under both conditions.

Deployment-level triggers are only supported on the initiating server’s side of the deployment.

You configure deployment-level Deploy and Run triggers and scripts within the dnrDeploymentJob element:

<deployment ...><dnrDeploymentJob location="source" when="after" state="success"><script .../>

</dnrDeploymentJob>...

</deployment>

The dnrDeploymentJob has the following associated attributes:

location — indicate indicates whether the Deploy and Run script is taking place on the source or target. This value is fixed as source.

when — indicate whether the script should be executed before (before) or after (after) the deployment of the particular directory. There is no default value. You must specify one of the options.

state — indicate whether the Deploy and Run script should run as a result of the success (success) or failure (failure) of the deployment, or whether it should always run in either case (always). Default value is always.

Within the dnrDeploymentJob element is the script element where the particular script that is run when triggered is specified. See “Scripting” on page 227 for more information.

217

Deploy and Run

Table of Deployment-Level Triggers

The following table lists the different configurations for deployment-level triggers. The table also lists the behavior that takes place for each configuration if you instruct the Deploy and Run script to send a return code to OpenDeploy by printing the following:

<response code="-2"/>\n

to STDOUT. Each response code behavior is listed, depending on whether the deployment is transactional or not. In some cases, the behavior is the same for both transactional and non-transactional deployments.

Task-Level Triggers

Task-level, or microdeploy, triggers occur within the course of the deployment between the time the initial connection is made between the source and targets, and when the disconnection between the hosts occurs. Unlike deployment-level triggers which are only associated with the complete deployment, task-level triggers are associated with a specific deployment action, such as a deployment to a particular target in a fan-out deployment, or a particular leg in a multi-tiered deployment.

Task-level triggers can be associated with the following events:

Deployment of a particular file.

Deployment of a particular directory.

Running of a particular deployment definition.

Deployment-based definitions are triggered by different stages of the deployment process.

File- and directory-based Deploy and Run definitions are data-oriented triggers that run when the deployed file or directory matches a specified pattern. These types of triggers are not supported in transactional deployments.

Configuration Transactional Response Code Behavior

<dnrDeploymentJoblocation="source"when="before">

yes Deployment runs regardless, and returns status Completed and code 0.no

<dnrDeploymentJoblocation="source"when="after">



Triggers

You configure task-level Deploy and Run within the deployNRun element, which is a child element of the execDeploymentTask element. Task-level triggers are associated with a particular definition within the deployment configuration. In the deployment configuration, the particular definition element’s name is specified by the execDeploymentTask element’s useDefinition attribute value. For example, if in a deployment the following definition was configured:

<definition name="webfiles"><source>...

</source><target>...


Then any task-level Deploy and Run triggers and scripts you want to be associated to that definition and its source-target file location pairing would be configured:

<deployment ...>...<execDeploymentTask useDefinition="webfiles"><deployNRun>

...</deployNRun>


Within the deployNRun element is the configuration for the various supported task-level triggers and scripts:

<deployment ...><dnrDeploymentJob location="source" when="after" state="success"><script .../>

</dnrDeploymentJob>...<execDeploymentTask useDefinition="webfiles"><deployNRun>

<dnrFile ...><script .../>

</dnrFile><dnrDir ...><script .../>

</dnrDir><dnrDeployment ...><script .../>

</dnrDeployment></deployNRun>


219

Deploy and Run

Here is a list of child elements associated with the deployNRun element:

dnrDeployment — specifies under what conditions a deployment itself can trigger a Deploy and Run script.

dnrFile — specifies under what conditions deployed files can trigger a Deploy and Run script.

dnrDir — specifies under what conditions deployed directories can trigger a Deploy and Run script.

You can configure any number of these triggers in any combination with each other. The following sections describe each type of trigger in detail.

Deployment-Based

You can configure OpenDeploy to begin a Deploy and Run script when the deployment configuration itself is run. This type of Deploy and Run is known as being deployment-based. You enable this feature by defining the dnrDeployment element in your Deploy and Run configuration. The dnrDeployment element has the following associated attributes:

location — indicate whether the Deploy and Run script is taking place on the source (source) or target (target) server. There is no default value. You must specify one of the options.

when — indicate whether the script should be executed before (before) or after (after) the deployment occurs. There is no default value. You must specify one of the options.

Evaluation of the area and previousArea attribute values in TeamSite comparison deployments with respect to the latest and next-to-latest editions, occurs before the running of any Deploy and Run scripts.

triggerPoint — indicate whether the Deploy and Run script should run at the time or connect between the source and server (connect), during the transfer of content (transfer), at the time of disconnect (disconnect), or when a transactional deployment is rolled back following a deployment failure (rollback). If no value is specified, OpenDeploy defaults to certain settings depending on the specified value of the when attribute.

when="before" — trigger occurs after the source-target connect occurs.

when="after" — trigger occurs after the content transfer occurs.


If the when attribute is set to before, then the state attribute is implicitly set to always, because there has been no deployment yet to determine success or failure.


Triggers

There are several deployment stages in a task where you can assign Deploy and Run triggers. You can specify the stage by the pairing of the when and triggerPoint attribute values. Unless otherwise stated, these pairings can apply whether the location is on the source side (location="source") or target side (location="target").

The following stages and their associated configurations are supported:

At the beginning of the task:

when="before" triggerPoint="connect"

This stage is only supported on the source side (location="source").

Following the source-target connection:

when="after" triggerPoint="connect"

As an option, you can omit the triggerPoint attribute from this configuration and still have the same result. You might want to configure the trigger in this way if you want to retain backwards deployment configuration compatibility with previous OpenDeploy releases. Otherwise, it is recommended you retain the triggerPoint attribute in the configuration.

At the beginning of the transfer of content:

when="before" triggerPoint="transfer"

This stage is only supported on the source side (location="source"), and only for directory comparison-based deployments. TeamSite comparison- and file list-based deployments are not supported by this configuration.

If you use this configuration, you must also have the deployment manifest feature enabled within the base server or receiver configuration file. Refer to “Specifying the Deployment Information Stream Format” on page 125in the OpenDeploy Installation Guide for more information.

At the ending of the transfer of content:

when="after" triggerPoint="transfer" or

when="before" triggerPoint="disconnect"

As an option, you can omit the triggerPoint attribute from this configuration and still have the same result. You might want to configure the trigger in this way if you want to retain backwards deployment configuration compatibility with previous OpenDeploy releases. Otherwise, it is recommended you retain the triggerPoint attribute in the configuration.

At the end of the task:

when="after" triggerPoint="disconnect"

This stage is only supported on the source side (location="source").

At the conclusion of a rollback that occurs when a transactional deployment fails:

when="after" triggerPoint="rollback"

This stage is only supported on the target side (location="target") and when a failure occurs (state="failure").

221

Deploy and Run

If any non-supported combination of these values is present in the deployment configuration, then the Deploy and Run script will not trigger when that deployment is run.


<dnrDeployment location="source" when="after" triggerPoint="transfer"state="failure">...

</dnrDeployment>

the Deploy and Run script triggers when this particular deployment configuration is run. The script originates at the source, and is executed at the conclusion of the transfer of content of a failed deployment.

Note that the following configurations are not supported for deployment-based triggers:

location="target" when="before" triggerPoint="connect"

location="target" when="before" triggerPoint="transfer"

location="target" when="after" triggerPoint="disconnect"

File-Based

You can configure OpenDeploy to begin a Deploy and Run script when a certain type or class of files are deployed. This type of Deploy and Run is known as being file-based. It is supported only for non-transactional deployments, and only on the target side. You enable this feature by defining the dnrFile element in the Deploy and Run configuration. File-based Deploy and Run is not available for use with transactional deployments.

The dnrFile has the following associated attributes:

location — indicate where the Deploy and Run script is taking place. The only currently supported option is target.

when — indicate whether the script should be executed before (before) or after (after) the deployment of the particular file. There is no default value. You must specify one of the options.

state — indicate whether the Deploy and Run script should run as a result of the success (success) or failure (failure) of the deployment, or whether it should always run in either case (always) . Default value is always.


mask — enter the regular expression to be matched against filenames to determine if the script will be executed. If you include file path separators in your mask value, you must use the path syntax supported by your OpenDeploy server.


mask=".*\.html$"


Triggers

any file with the file extension .html in the specified path will trigger the script defined within the Deploy and Run configuration.


<dnrFile location="target" when="before" state="always"mask=".*\.exe$">...

</dnrFile>

the Deploy and Run script, when triggered, will be located on the target. It will occur before a file matching the value of the mask attribute is deployed. OpenDeploy will trigger the script whether the deployment is successful or not. (If the when attribute is set to before, the state attribute is implicitly set to always because there has been no deployment yet to determine success or failure.) The mask attribute value .*\.exe$ indicates that the script will start each time a file with the extension .exe is deployed.

If you are not familiar with regular expressions, consult a reference manual such as Mastering Regular Expressions by Jeffrey Friedl.

Directory-Based

You can configure OpenDeploy to begin a Deploy and Run script when a certain type or class of directories are deployed. This type of Deploy and Run is known as being directory-based. It is supported only for non-transactional deployments, and only on the target side. You enable this feature by defining the dnrDir element in the Deploy and Run configuration. Directory-based Deploy and Run is not available for use with transactional deployments.

The dnrDir has the following associated attributes:

location — indicate where the Deploy and Run script is taking place. The only currently supported option is target.

when — indicate whether the script should be executed before (before) or after (after) the deployment of the particular directory. There is no default value. You must specify one of the options.



mask — enter the regular expression specifying the directories that, when deployed, will trigger the script. You must use the path syntax supported by your OpenDeploy server. The script is triggered only when the directory itself is deployed on the target. Deploying a file that resides within the directory will not trigger the script.

223

Deploy and Run


mask="cgi-bin$"

any directory named cgi-bin that is deployed will trigger the script.


<dnrDir location="target" when="after" state="success" mask="Temp$">...

</dnrDir>

the Deploy and Run script, when triggered, will be located on the target. It will occur after a directory matching the value of the mask attribute is deployed, and only if the deployment is successful. The mask attribute value Temp$ indicates that the script will start each time a directory with the name Temp is deployed.

If you are not familiar with regular expressions, consult a reference manual such as Mastering Regular Expressions by Jeffrey Friedl.

Reverse Deployments

When performing reverse deployments, the location attribute value source really means reverse target and the value target means reverse source. Figure 2 shows how the source mars and target venus communicate in a reverse deployment that contains a Deploy and Run.

Figure 2: Deploy and Runs in Reverse Deployments

As the initiator of the deployment, mars is source. However, in the context of a reverse deployment, it is the reverse target because it receives files from the reverse source.

mars(source)

(reverse target)

venus(target)

(reverse source)

OpenDeploy references a reverse deployment configuration containing a Deploy and Run


Base server host initiates reverse deployment to reverse source.


Triggers

Table of Task-Level Triggers

The following table lists the different configurations for task-level triggers.

Source-side triggers are indicated by the location="source" attribute value. Target-side triggers are indicated by the location="target" attribute value.

The table also lists the behavior that takes place for each configuration if you instruct the Deploy and Run script to send a return code to OpenDeploy by printing the following:

<response code="-2"/>\n

to STDOUT. Each response code behavior is listed, depending on whether the deployment is transactional or not. In some cases, the behavior is the same for both transactional and non-transactional deployments.


<dnrDeploymentlocation="source"when="before"triggerPoint="connect">


<dnrDeploymentlocation="source"when="after"triggerPoint="connect">

yes Deployment is aborted, and returns status Failed and code 2.no

<dnrDeploymentlocation="source"when="before"triggerPoint="transfer">

Not applicable when eventReporting is disabled and infoStreamFormat="log".

yes Deployment is aborted, and returns status Failed and code 2.

no

<dnrDeploymentlocation="source"when="after"triggerPoint="transfer">

yes Deployment rolls back, and returns status Failed and code 2.

no Deployment is aborted, and returns status Failed and code 2.

<dnrDeploymentlocation="source"when="before"triggerPoint="disconnect">



<dnrDeploymentlocation="source"when="after"triggerPoint="disconnect">


<dnrDeploymentlocation="target"when="after" triggerPoint="connect">

yes Deployment is aborted, and returns status Failed and code 2.no

225

Deploy and Run

<dnrDeploymentlocation="target"when="after"triggerPoint="transfer">

and

<dnrDeploymentlocation="target"when="before"triggerPoint="disconnect">

These are both the same trigger points.



<dnrFilelocation="target"when="before">

yes Not supported.

no Deployment is aborted midstream, and returns status Completed with Errors and code 9.

<dnrFilelocation="target"when="after">

yes Not supported.


<dnrDirlocation="target"when="before">

yes Not supported.


<dnrDirlocation="target"when="after">

yes Not supported.




Scripting

Scripting

The Deploy and Run script is defined by the script element. Once the script is in place, the script element will integrate it into the Deploy and Run configuration. The script element has the following attributes:

cmd — enter the full path to the command which OpenDeploy should run, if triggered, as well as any accompanying flags or options. Using a relative path is not supported.

You can also specify an executable invocation line. For example:

cmd="C:\bin\email_to_admin.bat -user [email protected]" or

cmd="/bin/mail [email protected] < /tmp/message.txt"

If the command you are going to run requires a scripting engine, the scripting engine must be explicitly entered using the full path. For example:

cmd="/bin/sh /usr/local/bin/email_to_admin.sh -u

[email protected]" or

cmd="/usr/local/bin/iwperl /path/to/script.pl"

where — enter the location to where OpenDeploy must go before executing the script. For example:

where="/tmp" or

where="C:\temp"

You must use the path syntax supported by your OpenDeploy server. Forward slashes (“/”) can be used for either Windows or UNIX hosts, while backslashes (“\”) are only permitted on Windows hosts.

The where attribute is optional. If you do not specify a value, the process takes place in the root directory.

as (UNIX only) — enter a different user name or user ID under which you will run the script. This option allows you to run the script as a different user. In the following example:

as="rroe" or

as="110"

you can run the script as rroe or its user ID 110 rather than your regular user name. By default, the script runs as the user who invokes the deployment when the base server or receiver is running as root. If the base server or receiver is running as a non-root user, then the script is run as the same user as the base server or receiver process.

async — indicate whether or not to run the script asynchronously. Exercise caution when using this mode, as it could cause many scripts to be run simultaneously. The output from scripts run asynchronously is not captured. Default value is no.

227

Deploy and Run


<dnrDeployment location="source" when="after" triggerPoint="connect"state="always"><scriptcmd="/bin/sh /usr/local/bin/email_to_admin.sh" where="/tmp"async="yes"/>

</dnrDeployment>

the Deploy and Run configuration will trigger the /bin/sh /usr/local/bin/email_to_admin.sh script (which sends deployment confirmation email messages to the OpenDeploy administrator) after the deployment has completed, whether successful or not. The script is also allowed to run asynchronously.


Scripting

The following configuration sample shows Deploy and Run configured both at the deployment level and at the task level. The definition with which the task-level Deploy and Run configuration is associated is also displayed.


<remoteDiff area="/website/files"><pathSpecification>



</source><target><targetFilesystem area="/website/files"/>

<replicationFarmLink><internal name="WebServers"/>


</definition><deployment transactional="no">

<dnrDeploymentJob location="source" when="after"triggerPoint="connect" state="success">

<script cmd="/default/main/dev/scripts" as="webmaster"where="/temp" async="yes"/>

</dnrDeploymentJob><execDeploymentTask useDefinition="webfiles><deployNRun>

<dnrFile location="target" when="before" state="success"mask="\.txt$"><script cmd="email_to_admin.sh" as="webmaster" where="/temp"

async="no"/></dnrFile><dnrDir location="target" when="after" state="failure"mask="exes"><script cmd="mail [email protected] < message.txt"

as="webmaster" where="/temp" async="no"/></dnrDir><dnrDeployment location="source" when="after" triggerPoint=""state="success"><script cmd="/default/main/dev/scripts" as="webmaster"

where="/temp" async="yes"/></dnrDeployment>

</deployNRun></execDeploymentTask>

</deployment>

Specifying Allowed Deploy and Run Scripts

You can configure your base server or receiver to only allow certain Deploy and Run scripts to be run. Refer to “Specifying Allowed Deploy and Run Scripts” on page 139 in the OpenDeploy Installation Guide for more information.

229

Deploy and Run

Ordering of Deploy and Run Scripts

Deploy and Run scripts that are specified to be triggered at the same point in the deployment are run in the order they appear in the configuration. For example, in the following configuration:

...<deployment>

<dnrDeploymentJob location="source" when="after" state="success"><script async="no" cmd="/user/scripts/script_D"/>

</dnrDeploymentJob><dnrDeploymentJob location="source" when="after" state="success"><script async="no" cmd="/user/scripts/script_C"/>

<dnrDeploymentJob><execDeploymentTask useDefinition="def1"><dnrDeployment location="source" when="after"

triggerPoint="transfer" state="success"><script async="no" cmd="/user/scripts/script_A"/>

</dnrDeployment><dnrDeployment location="source" when="after"

triggerPoint="transfer" state="success"><script async="no" cmd="/user/scripts/script_B"/>

</dnrDeployment></execDeploymentTask>

</deployment>...

script_C and script_D are both configured to be triggered under the following conditions:

At the source (location="source")

After the deployment of files (when="after")

When the deployment result is successful (state="success")

Since they are configured to be triggered under the same conditions, they would be run in the order they appear in the deployment configuration:

1. script_D

2. script_C

Similarly, script_A and script_B are configured to be triggered under the same circumstances as each other (location="source" when="after" triggerPoint="transfer"), and therefore would be run in the order they appear in the deployment configuration:

1. script_A

2. script_B


Usage of the Deployment Information Stream

The Deploy and Run execution order is maintained only for synchronous Deploy and Run scripts using the following configuration:

<script async="no" cmd="script_X"/>

Usage of the Deployment Information Stream

OpenDeploy generates an internal list of path items deployed or to be deployed each time a task-level Deploy and Run triggers. This data can be streamed into a Deploy and Run script. The Deploy and Run script consumes the stream, after which you can manipulate it to meet your needs. Deployment-level triggers (those configured with the dnrDeploymentJob element) do not support the use of this list. See “Triggers” on page 216 for more information on trigger types.

The following steps take place whenever Deploy and Run calls a script:

1. stdin of the spawned Deploy and Run process is set to receive an XML representation of the OpenDeploy in-memory log in its current state.

2. The script executes.

3. The receiver XML log is transferred to the sender.

Use the Perl module IWXML.pm to process either information stream format from a Perl program. This module resides in the following location:

od-home/solutions/perl

Information Stream Output Formats

This release of OpenDeploy contains a newer method of capturing this streamed information into a new manifest format. Older releases of OpenDeploy used a legacy log format. Both methods are supported.

Refer to “Specifying the Deployment Information Stream Format” on page 125 in the OpenDeploy Installation Guide for information on configuring these formats in your server configuration file.

231

Deploy and Run

The following is an example of the information stream outputted in the manifest format:

<iwodManifest type="transfer"><profile srcPlatform="UNIX" srcDir="/space/ODadvanced/OpenDeployNG/solutions/perl" trgPlatform="UNIX" trgDir="/space/ODadvanced/OpenDeployNG/tmp/viewstream"/><item path="deletefile.txt" type="FILE" reason="missing-in-src" action="DELETE" status="SKIPPED" statusDetail="" srcDir="/space/ODadvanced/OpenDeployNG/solutions/perl" trgDir="/space/ODadvanced/OpenDeployNG/tmp/viewstream"/><item path="modfile.txt" type="FILE" reason="src-is-newer" action="UPDATE" status="COMPLETED" statusDetail="" srcDir="/space/ODadvanced/OpenDeployNG/solutions/perl" trgDir="/space/ODadvanced/OpenDeployNG/tmp/viewstream"/><item path="newfile.txt" type="FILE" reason="missing-in-dest" action="NEW" status="COMPLETED" statusDetail="" srcDir="/space/ODadvanced/OpenDeployNG/solutions/perl" trgDir="/space/ODadvanced/OpenDeployNG/tmp/viewstream"/></iwodManifest>

The following is an excerpt of the same information stream outputted in the log format:

...<log_element target="" action="0" date="1043364928" result="3" response="directive[get ./new.txt]" /><log_element target="" action="0" date="1043364928" result="1" response="Receiving item(./new.txt)" /><log_element target="" action="0" date="1043364928" result="3" response="dir for tempfile [/space/ODadvanced/OpenDeployNG/tmp/viewstream]" /><log_element target="" action="0" date="1043364928" result="3" response="-- Processing file(/space/ODadvanced/OpenDeployNG/tmp/viewstream/new.txt)" /><log_element target="" action="0" date="1043364928" result="3" response="file created[/space/ODadvanced/OpenDeployNG/tmp/viewstream/new.txt.iwtmp]" /><log_element target="" action="0" date="1043364928" result="3" response="Renamed [/space/ODadvanced/OpenDeployNG/tmp/viewstream/new.txt.iwtmp] to [/space/ODadvanced/OpenDeployNG/tmp/viewstream/new.txt.iwnew]" /><log_element target="/space/ODadvanced/OpenDeployNG/tmp/viewstream/new.txt" action="1" date="1043364928" result="0" response="" /><log_element target="" action="0" date="1043364928" result="3" response="directive[reason missing-in-dest]" />...

The manifest format provides a more concise presentation that is easier to read and understand.

For DTD information on log and manifest formats, refer to Chapter 11, “Information Stream Log Format DTD” on page 223 and Chapter 17, “OpenDeploy Manifest DTD” on page 269 in the OpenDeploy Reference.


Disabling Deploy and Run Executions on the Target

Disabling Deploy and Run Executions on the Target

You can disable Deploy and Run executions on the target of a deployment where Deploy and Run is configured in the base server or receiver configuration file. This ability does not have any effect on the sending server’s Deploy and Run executions specified in the deployment configuration.

To disable the running of Deploy and Run executions on the target, you must assign the dnrProperties element’s allowDnrExecution attribute value to no in the target’s base server or receiver configuration file. For example:

<deployServerConfiguration>...<dnrProperites allowDnrExecution="no" .../>

...</deployServerConfiguration>

To run Deploy and Run executions on the target without restrictions, specify the value as yes. The default value is yes.

Deploying to a Package File Using Deploy and Run

If it is impossible or impractical to deploy files directly to your targets, perhaps because of a firewall or some other obstruction, OpenDeploy can deploy files into a package file on another host, or even the source itself. You can transport the file to the targets using an approved means, and install the deployed files directly on the targets. OpenDeploy uses the Deploy and Run feature as the basis for creating package files.

In Figure 3, a direct transmission of files between the source and the target is not possible. The OpenDeploy administrator configures a deployment to write the deployed files to a package file, such as a .tar or .zip file, on the source. That package file is then copied to a transportable medium, such as a tape, and is subsequently manually installed on the target.

Figure 3: Package Deployment

OpenDeploy references a package deployment configuration.

target(production server)

source(development server)

Deployed files are written to a .tar or .zip file.

Package file is copied onto a transportable medium.

Package file is expanded and installed on target.

233

Deploy and Run

To create a package file, follow these steps:

1. Configure a deployment that deploys files to the source itself. This involves the following tasks:

Specifying your source in the nodes configuration file.

Adding your host and target directory to the allowedHosts and allowedDirectories elements in your base server configuration file.

2. Configure the deployment with a Deploy and Run script that writes the deployed files to a package file after a successful deployment. On an OpenDeploy server running on a UNIX host, this would appear in your deployment configuration as the following:

<dnrDeployment location="target" when="after" state="success"><script cmd="tar cvf package_file.tar target_area" async="no"/>

</dnrDeployment>

where package_file.tar is the name of the package file and target_area is the path to the location where the deployed files will reside after completing the deployment.

On an OpenDeploy server running on Windows, you would substitute a Windows packaging command for the cmd attribute.

Secure Invocation of External Applications on UNIX

The Deploy and Run scripting facility launches external applications on UNIX servers using the deployment user’s ID as the process owner. This applies to both sender- and receiver-side Deploy and Run invocations. This feature helps prevent a sender from launching potentially harmful operations that the user is not permitted to perform on sending and receiving systems.

Although this feature applies only to deployments running on UNIX hosts, deployments can be initiated from OpenDeploy running on either UNIX or Windows hosts. By default, the Deploy and Run script will run as the user who invoked the deployment if the user attribute is unspecified in the Deploy and Run script element.


Chapter 6

Scheduled Deployments

You can schedule a deployment to take place any time day or night. You can schedule the deployment to run on a one-time only basis, or recurrently on intervals from a few minutes to monthly. Scheduling deployments frees individuals from having to manually start a deployment.

You can schedule deployment to take place at low network traffic periods such as evenings and weekends when they will not interfere with other tasks. You can also schedule a deployment to take place in conjunction with other events, such as a product announcement.

Any individual holding an Administrator role can schedule any deployment on that OpenDeploy server. Individuals with User accounts on an OpenDeploy server can schedule those deployments assigned to them. Individuals holding either an Administrator or User role can view all schedules.

You can schedule deployments using the user interface or from the command line using command-line tools.

235


Scheduling from the User Interface

You can create, edit, delete, and view deployment schedules in the OpenDeploy user interface. Creating and editing schedules is performed in the New Schedule window (Figure 1).

Figure 1: New Schedule Window

Here you can specify the time and date the deployment will start. If you want it to occur more than once on a regular basis, such as daily or weekly, you can select that as well. Depending on the frequency level you assign to the scheduled deployment, the New Schedule window will prompt you for additional scheduling information. You can also specify an end date when the schedule is no longer in effect.

Resolving Time Zone Differences

When scheduling deployments, the time zone of the sending OpenDeploy server is used. For example, if your sender resides in Eastern Standard Time (EST), and you connect to it through the browser-based user interface, or through a telnet session, scheduling the job for 10:00 AM indicates 10:00 AM EST.



Scheduling Deployments

To schedule a deployment, follow these steps:

1. Select Schedules > New Schedule to display the New Schedule window.

2. Select the OpenDeploy server whose deployments you want to schedule from the Selected Server list.

3. Select the deployment you want to schedule from the Deployment list.

4. Select the month, day, and year on which you want to the deployment to start from the Start Date lists. You can also click Calendar to display a pop-up calendar window. Select the date in this window, and it will automatically be placed in the Start Date lists.

5. Select the hour and minute on which you want the deployment to start from the Start Time lists. Use the 24-hour clock system, such as 13 to indicate 1 pm.

6. (optional) Enter the deployment instance name in the Instance Name box. The value you enter is a is a suffix that is appended to the deployment name. This option is used to create unique deployment names for each instance of a deployment configuration. See “Scheduling Deployment Instances” on page 245 for more information.

7. (optional) Enter the key/value parameter substitution value in the Parameters box. See “Applying Parameter Substitution to Scheduled Deployments” on page 244 for more information. Note that if your value contains spaces, you should not enclose the param-eter value in quotes, as is the case when specifying parameter substitution from the command line.

8. Enter a description of the deployment in the Description box. For example:

This is a deployment that updates all our product pages nightly.

9. Select one of the following options from the Deployment Frequency list:

Figure 2: New Schedules Frequency Features

Once — select if the deployment is not recurring.

sub-hourly hourly daily

weekly

monthly

237


Sub-hourly — select to enable deployments recurring in a fixed number of minutes. The Sub-Hourly section appears at the bottom on the window (Figure 2). Enter the interval in minutes between deployments in the Minute Interval box.

Hourly — select to enable deployments recurring in a fixed number of hours. The Hourly section appears at the bottom on the window (Figure 2). Enter the interval in hours between deployments in the Hour Interval box.

Daily — select to enable deployment recurring in a fixed number of days. The Daily section appears at the bottom on the window (Figure 2). Enter the interval in days between deployments in the Day Interval box.

Weekly — select to enable deployment recurring in a fixed number of weeks, and on the same day. The Weekly section appears at the bottom of the window (Figure 2). Enter the interval in weeks between deployments in the Week Interval box. Select the day of the week the deployment will occur in the Day of the Week list.

Monthly — select to enable deployments recurring every month on the same date. The Monthly section appears, containing a 31 day calendar (Figure 2). Check each date that the monthly deployment will occur. If you select a date that does not occur every month, for example “31,” then that deployment will not occur until the next month that includes that date. A date of “31” would skip June, but take place in July.

If you selected any deployment frequency option other than Once, continue to the next step. Otherwise, click Save to complete the schedule.

10. Check the Use End Date & Time box if you want to designate an end date for the recurring deployments (Figure 3). If you do not check this box, the recurring deploy-ments will take place indefinitely.

Figure 3: Schedule End Date and Time

11. Select the month, day, and year on which you want to the deployment to end from the End Date lists. You can also click Calendar to display a pop-up calendar window. Select the date in this window, and it will automatically be placed in the End Date lists.

12. Select the hour and minute on which you want the recurring deployment to end from the End Time lists.



13. Click Save to complete the new schedule. The Deployment Schedules window appears (Figure 4), displaying the new schedule you just created along with the other scheduled deployments.

Figure 4: Deployment Schedules Window

Viewing Schedules

Each time you add a schedule, that schedule is displayed in the Deployment Schedules window (Figure 4). You can also display all the scheduled deployments for an OpenDeploy server by selecting view all from the Deployment list (Figure 5).

Figure 5: Deployment Schedules Window Displaying All Scheduled Deployments

Viewing Scheduled Deployment Information

To view a deployment schedule, follow these steps:

1. Select Schedules > View Schedules to display the Deployment Schedules window.

2. Select the name of the OpenDeploy server whose deployment scheduling information you want to view from the Selected Server list.

3. Select the name of the deployment group in which the deployment configuration resides from the Deployment Group list.

239



4. Select the deployment whose scheduling information you want to view from the Deployment list, or select view all to display all of them.

The following information is displayed regarding each deployment listed:

Name — displays the name of the deployment. If you entered an instance name for the scheduled deployment, that name is included in parentheses.

ID — displays the identification number of the scheduled deployment.

Start Date — displays the day, month, and year specified as the start date when the schedule was added. This may not be the same as the date when the first scheduled deployment will occur.

Start Time — displays the time on the start date specified as the start time when the schedule was added. This may not be the same as the time when the first scheduled deployment will occur.

End Date — displays the day, month, and year specified as the end date when the schedule was added. This may not be the same as the date when the last scheduled deployment will occur.

End Time — displays the time on the end date specified as the end time when the schedule was added. This may not be the same as the time when the last schedule deployment will occur.

Frequency — displays how often the recurring scheduled deployment runs: sub-hourly, hourly, daily, weekly, or monthly. If the schedule is monthly, the date during the month the scheduled deployment occurs is included.

Active — displays whether or not the scheduled deployment is active.

Editing Scheduled Deployments

To edit a scheduled deployment, follow these steps:



3. Select the deployment whose scheduling information you want to edit from the Deployment list. That scheduled deployment is displayed.

You can also select view all to display all the scheduled deployment for the OpenDeploy server.

4. Click Edit to display the Edit Schedule window if you want to change any aspect of the existing schedule. The Edit Schedule window looks and functions similarly to the New Schedule window. Here you can change any item of the scheduled deployment.

5. Make you changes and click Save.



Deleting Scheduled Deployments

To delete a scheduled deployment, follow these steps:





4. Click Delete to remove the schedule from the scheduler database. You will be prompted to confirm that you want to delete the schedule. If you confirm the deletion, that schedule will be removed from the Deployment Schedules window.

Activating and Deactivating Scheduled Deployments

When you creating a new schedule, it is automatically activated and will run at it scheduled start date. You can stop the scheduled deployment from occurring without deleting it by deactivating it.

To deactivate a scheduled deployment, follow these steps:





4. Click Hold to deactivate that deployment. The Active column will display no for that scheduled deployment, and the Hold button will change to Activate.

To reactivate a deactivated scheduled deployment, repeat the same steps you did to deactivate the deployment, and click Activate. The Active column will display yes for that scheduled deployment, and the Activate button will change to Hold.

241


Scheduling from the Command Line

You can use the following OpenDeploy command-line tools (CLTs) to perform the associated scheduling-related tasks:

iwodcmd schedadd — add schedules to deployment configurations.

iwodcmd schedget — view scheduling information on a selected deployment.

iwodcmd scheddelete — delete existing schedules from deployment configurations.

iwodcmd schedactivate — activate or deactivate a scheduled deployment.

Scheduling CLTs only can be run on the host where the OpenDeploy base server software is installed. Individuals attempting to use the following scheduling CLTs must have the authorization to run those deployments on the base server being used:

iwodcmd schedadd

iwodcmd scheddelete

iwodcmd schedactivate

Use of iwodcmd schedget does not require authorization.

See “Roles and Authorization” on page 71 for more information.

Adding a Schedule

To add a schedule to a deployment using the command line, follow these steps:


od-home/bin

2. Add a schedule for a deployment by entering the following command at the prompt:

iwodcmd [-odinst instName] schedadd deployment options

where deployment is the name of the deployment you are scheduling.

There are various options associated with the iwodcmd schedadd command-line tool. Here is a listing of these options, along with the usage syntax:

iwodcmd schedadd -h | -v

iwodcmd [-odinst instName] schedadd deployment [-r [n][m|h|d|w]] [-s [n][m|h|d|w]] [-e [n][m|h|d|w]]] [-c comment] [-inst instance] [-k "key=value"]+



-odinst instName Uses OpenDeploy instance instName.

deployment Name of the deployment being scheduled.



-r Repeat every N minutes, hours, days, or weeks.

-s [N][m|h|d|w] Time from current time to use as start date. The default is 1 minute from current time when the command is entered.

-e [N][m|h|d|w] Amount of time from current time to use as end date. The default end time is none. The scheduled deployment will continue indefinitely.

n A numerical value.

m Minutes.

h Hours.

d Days.

w Weeks.

-c comment Description of the deployment being scheduled. See “Use of Comments” on page 244 for more information.

-inst instance Includes the deployment instance name instance, which is a suffix that is appended to the deployment name. This option is used to create unique deployment names for each instance of a deployment configuration. See “Scheduling Deployment Instances” on page 245.

-k key=value Key/value substitution with "key=value" as the arg value. See “Applying Parameter Substitution to Scheduled Deployments” on page 244 for more information.

One-Time Only Deployments

If you only want to run the scheduled deployment once, you do not need to include any option to denote recurrence. In the following example, if you want to schedule the deployment reports to deploy a single time a week from now at the same time of day it is currently, you would enter the following command at the prompt:

iwodcmd schedadd reports -s 1w

243


Recurring Deployments

If you want your scheduled deployment to run indefinitely at the interval and time you specified, add the -r option and the time interval. You can also use the -s option and a time period to designate the time of day the deployment will start. Otherwise, the deployment will start at one minute past the time you enter the command. In the following example, if you wanted to schedule the deployment reports to run once a day starting at a time one hour from the time you are adding the schedule, you would enter the following command at the prompt:

iwodcmd schedadd reports -r 1d -s 1h

Recurring Deployments with End Dates

You can specify an end date on which a recurring deployment will cease by including the -e option and the amount of time from now that the recurring deployment will cease. If you do not include an end date, the scheduled deployment will occur indefinitely. In the following example, if you wanted the recurring scheduled deployment from the previous example to cease in two weeks, you would enter the following command at the prompt:

iwodcmd schedadd reports -r 1d -s 1h -e 2w

Use of Comments

You can add a comment to your scheduled deployment using the -c option. Your comment can be of any length and include spaces. However, if your comment includes spaces, you must enclose your comment in quotes. In the following example, a comment is added to the previous command:

iwodcmd schedadd reports -r 1d -s 1h -e 2w -c "quarterly businessreport"

Comments you add to a scheduled deployment are displayed with its corresponding scheduled deployment when you view deployments using the iwodcmd schedget command. This feature is also equivalent to the Description box contained in the New Schedule and Edit Schedule windows in the OpenDeploy browser-based user interface.

Applying Parameter Substitution to Scheduled Deployments

You can schedule deployments using parameter substitution, including specifying the parameter values, using iwodcmd schedadd. The iwodcmd schedadd command supports the -k parameter=value option for parameter substitution in the same manner as iwodcmd start. When you schedule a deployment that uses parameter substitution, you specify the attribute parameter and the substituted value using the following syntax:

iwodcmd schedadd deployment ... -k parameter=value

In the following example, the deployment reports has its remoteDiff element’s area attribute configured in the following manner:

remoteDiff area="$srcarea^"



If you wanted to schedule the deployment to run a single time a week from now at the same time of day it is currently, and also apply the value C:\temp to the parameter srcarea you would enter the following command at the prompt:

iwodcmd schedadd reports -s 1w -k srcarea=C:\temp

If either the parameter or its assigned value contained a space, then the entire combined parameter and value must be placed inside of quotation marks. For example, if the value of srcarea is:

C:\Program Files\monthly

then you would enter:

iwodcmd schedadd reports -s 1w -k "srcarea=C:\Program Files\monthly"

See “Parameter Substitution” on page 203 for a complete description of the parameter substitution feature.

Scheduling Deployment Instances

You can schedule a particular instance of a deployment using the -inst instance option with iwodcmd schedadd. Scheduling a deployment instance in this manner uses the following syntax:

iwodcmd schedadd deployment -inst instance

When you schedule a deployment using the instance feature, the instance name is combined with the deployment name. That combined name is used to track the deployment in the browser-based user interface

See “Specifying a Deployment Instance” on page 69 for a description and usage of the deployment instance feature.

Viewing Scheduled Deployment Information

You can access information on any schedule assigned to your deployment, or all the schedules together, using the iwodcmd schedget command-line tool. Several other scheduling-related command-line tools require the schedule ID and other scheduling information that you can get using this tool.

To view information on your deployments schedules, follow these steps:


od-home/bin

245


2. Display the schedule information of a deployment by entering the following command at the prompt:

iwodcmd [-odinst instName] schedget deployment options

where deployment is the name of the deployment.

There are various options associated with the iwodcmd schedget command-line tool. Here is a listing of these options, along with the usage syntax:

iwodcmd schedget -h | -v

iwodcmd [-odinst instName] schedget -a

iwodcmd [-odinst instName] schedget -d deployment

iwodcmd [-odinst instName] schedget -o deployment -j ID


-v Displays usage information.

-odinst instName Uses OpenDeploy instance instName.-a Gets all schedules. This is the default option.

-d deployment Gets all schedules for a particular deployment.

-o deployment Gets one schedule. Requires the deployment name and the deployment ID number.

deployment The name of the deployment configuration.

-j ID Specifies a job. The ID number of the deployment. Each time a deployment runs, that deployment is given a unique ID number. Similarly, when you schedule a deployment, that scheduled deployment is also given a issued a unique ID number. Use the -a option to see all the ID number for your deployment.

If you wanted to view the schedule information for all of the scheduled deployments residing on your OpenDeploy server, you would enter the following command at the prompt:

iwodcmd schedget -a

If you wanted to view all schedules for the deployment reports, you would enter the following command at the prompt:

iwodcmd schedget -d reports

If you wanted to view schedule information for the deployment reports with an ID number of “2,” you would enter the following command at the prompt:

iwodcmd schedget -o reports 2



Deleting a Schedule

To delete a schedule using the command line, follow these steps:


od-home/bin

2. Delete a schedule from a deployment by entering the following command at the prompt:

iwodcmd [-odinst instName] scheddelete deployment options


There are various options associated with the iwodcmd scheddelete command-line tool. Here is a listing of these options, along with the usage syntax:

iwodcmd scheddelete -h | -v

iwodcmd [-odinst instName] scheddelete deployment -j ID

iwodcmd [-odinst instName] scheddelete "dep_name_pattern*" [-j ID]



-odinst instName Uses OpenDeploy instance instName.deployment The name of the deployment configuration.

-j ID Specifies a job. The ID number of the deployment. Each time a deployment runs, that deployment is given a unique ID number. Similarly, when you schedule a deployment, that scheduled deployment is also given a issued a unique ID number. Use the iwodcmd schedget -a command to see all the ID number for your deployment.

"dep_name_pattern*" Deletes schedules based on a wild card name selection, with an optional job identifying number (-j option). The wild card pattern must be quoted ("sample*"). If the optional job identifying number (-j option) is not present, all scheduled deployments beginning with "dep_name_pattern*" will be deleted. If the job identifying number is present, only a scheduled deployment beginning with dep_name_pattern and having a job identifying number equal to the specified value will be deleted.

247


Because a deployment can have multiple schedules assigned to it, each individual schedule is issued its own unique ID number by OpenDeploy at the time of its creation. You must specify this ID number when you use the iwodcmd scheddelete command to ensure that only the schedule you want is being deleted. You can determine this ID value by using the iwodcmd schedget command-line tool. See “Viewing Scheduled Deployment Information” on page 245 for more information.

For example, if you wanted to delete a schedule for the deployment reports with the ID of “5,” you would enter the following command at the prompt:

iwodcmd scheddelete reports 5

Activating and Deactivating a Schedule

When you creating a new schedule, it is automatically activated and will run at it scheduled start date. You can stop the scheduled deployment from occurring without deleting it by deactivating it.

To activate or deactivate a schedule using the command line, follow these steps:


od-home/bin

2. Activate or deactivate a scheduled deployment by entering the following command at the prompt:

iwodcmd [-odinst instName] schedactivate deployment options




There are various options associated with the iwodcmd schedactivate command-line tool. Here is a listing of these options, along with the usage syntax:

iwodcmd schedactivate -h | -v

iwodcmd [-odinst instName] schedactivate -a deployment -j ID

iwodcmd [-odinst instName] schedactivate -a "dep_name_pattern" [-j ID]

iwodcmd [-odinst instName] schedactivate -d deployment -j ID

iwodcmd [-odinst instName] schedactivate -d "dep_name_pattern" [-j ID]



-odinst instName Uses OpenDeploy instance instName.-a deployment Activates a specific scheduled deployment.

-a "dep_name_pattern*" Activates a scheduled deployment with an optional jobID (-j option) using a wild card pattern format. The wild card pattern must be quoted ("sample*"). If no -j option is present, all scheduled deployments beginning with dep_name_pattern will be changed.

If a -j option is present, only a scheduled deployment beginning with dep_name_pattern and having a jobID equal to the job identifying number will be changed.

-d deployment Deactivates a specific scheduled deployment, using the deployment and -j ID options.

-d "dep_name_pattern*" Deactivates a scheduled deployment with an optional job identifying number (-j option), using a wild card format. The selection rules are the same as those stated in the schedule activation description above.

deployment The name of the deployment configuration.

-j ID Specifies a job. The ID number of the deployment. Each time a deployment runs, that deployment is given a unique ID number. Similarly, when you schedule a deployment, that scheduled deployment is also given a issued a unique ID number. Use the iwodcmd schedget -a command to see all the ID number for your deployment.

249


If you wanted to deactivate the scheduled deployment reports with an ID of “5”, you would enter the following command at the prompt:

iwodcmd schedactivate -d reports 5

Conversely, to reactivate the deployment, you would enter the following command at the prompt:

iwodcmd schedactivate -a reports 5

Reactivating Schedules During or Past Their Effective Period

If a scheduled deployment is deactivated, either by selecting the Hold feature in the browser-based user interface, or by running the iwodcmd schedactivate command-line tool, reactivating it during or after the effective schedule period results in the following:

Reactivation during effective period — After the schedule is reactivated, all scheduled runnings of the deployment that have already past are ignored. OpenDeploy will run the next scheduled occurrence of the deployment.

Reactivation after effective period — OpenDeploy automatically deletes the scheduled deployment without running it.

See “Activating and Deactivating Scheduled Deployments” on page 241 for more information about activating and deactivating scheduled deployments using the browser-based user interface.

See “Activating and Deactivating a Schedule” on page 248 for more information on using the iwodcmd schedactivate command-line tool.


Chapter 7

Logging

OpenDeploy provides a variety of different types of logging information including:

Activities involving the base server or receiver (base server or receiver log).

Activities involving a deployment as a whole (macro deployment log) from both the sending and receiving servers.

Activities involving a specific source/target pair within a deployment (micro deployment log) from both the sending and receiving servers.

You can view and analyze logging information to determine the efficiency of your deployments, whether they are successful or not, and for general troubleshooting.

Log File Location

The default location for all log files is:

od-home/(od-instance)/log

You can specify another location for the base server and receiver log files by entering the path in the directory attribute of the logRules element in the corresponding base server or receiver configuration file (by default odbase.xml or odrcvr.xml). However, you cannot specify a different log file directory location in a deployment configuration. See “Logging Configuration Settings” on page 263 for more information.

Log File Permissions

On UNIX hosts, OpenDeploy log files have the permission 644.

251

Logging

Viewing Log Information

You can view log files using one of the following methods:

Text editor

OpenDeploy user interface

Viewing Log Files from a Text Editor

OpenDeploy log files are standard text files that can be opened with any standard text editor, including vi and Notepad.

Viewing Log Files from the OpenDeploy User Interface

You can view log files in the OpenDeploy user interface using the OpenDeploy Log Viewer window (Figure 1). The OpenDeploy Log Viewer window is a separate browser window that appears when you click a View Log button in a window.

Figure 1: OpenDeploy Log Viewer Window

Each log you select to view is displayed in a separate browser window which allows you to view multiple logs simultaneously.

The format and structure of the various logs are essentially the same. The deployment log windows include the name of the deployment associated with the logs. Here is a description of the log windows:

Server — displays the name of the OpenDeploy server sending and receiving the deployment.

Log Type — displays the type of log file being displayed, such as a server global log (base server or receiver log) or a deployment macro or micro log for a deployment sent or received.


Viewing Log Information

Deployment (deployment logs only) — displays the name of the deployment associated with the displayed log.

Path — displays the absolute path to the directory containing the log file being displayed.

File — displays the name of the log file being displayed. The following types of log files can be displayed in this window:

server_odbase.log — indicates the log file is a base server log.

server_odrcvr.log — indicates the log file is a receiver log.

src.deployment.log — indicates the log file is a source macro deployment log.

rcv.deployment.definition.target-server.log — indicates the log file is a receiver macro deployment log.

src.deployment.definition.source-server.to.target-server.log — indicates the log file is a source micro deployment log.

rcv.deployment.definition.source-server.to.target-server.log — indicates the log file is a receiver micro deployment log.




source-server — the name of the source sending the deployment.

target-server — the logical name of the target receiving a deployment as it appears in the nodes configuration file of the sending server.

<< button — click to display the beginning of the log.

< button — click to display the previous portion of the log.

> button — click to display the next portion of the log.

>> button — click to display the end of the log.

Page Size box — enter the number of lines of the deployment log you want to view. You can enter the exact number, or click the arrow buttons up and down in increments of 10 from the existing number. You can range in size from 10 to 1000 lines. You must click Refresh to implement the number you entered.

Position box — enter the proportional location percentage (0-100) of the log file to be displayed. You can enter the exact number, or click the arrow buttons up and down in increments of 10. For example, the beginning of the log would be 0, while the center would be 50. You must click Refresh to implement the number you entered.

Refresh button — click to refresh the log and to read in fresh data with the Page Size and Position values you entered.

253

Logging

Base Server Logging

All activities concerning the OpenDeploy base server are written to the base server log. Base server log entries include information on:

Starting up OpenDeploy services and daemons

Adding, removing, and modifying the Administrator and User roles of individuals

Starting deployments

Receiving deployments

Adding schedules for deployments

Starting a scheduled deployment

Requests from individuals with User roles that have been denied due to insufficient authorization

Error information on requested operations

Reviewing the base server log is an effective method of determining the activities of your OpenDeploy base server, and of troubleshooting problems.

Here is an example of base server log entries:

BEGIN LOG: Logfile [C:\Interwoven\OpenDeployNG\log\jmoorebw2k_odbase.log] ---------API: 2001-11-12 13:09:55 PST GMT-08:00 Using time zone: Pacific Standard TimeAPI: 2001-11-12 13:09:55 PST GMT-08:00 Using locale: en_USAPI: 2001-11-12 13:09:55 PST GMT-08:00 Using OpenDeploy home directory: C:\INTERW~1\OPENDE~1API: 2001-11-12 13:09:55 PST GMT-08:00 Using server config file specified in deploy.cfg: C:\INTERW~1\OPENDE~1\etc\odbase.xmlAPI: 2001-11-12 13:09:55 PST GMT-08:00 Using server nodes config file specified in deploy.cfg: C:\INTERW~1\OPENDE~1\etc\odnodes.xmlAPI: 2001-11-12 13:09:59 PST GMT-08:00 Using server log directory C:\Interwoven\OpenDeployNG\log specified in server config file.API: 2001-11-12 13:09:59 PST GMT-08:00 Using OpenDeploy Server log file C:\Interwoven\OpenDeployNG\log\jmoorebw2k_odbase.log.

By default, the base server log file resides in the following location:

od-home/(od-instance)/log/server_odbase.log

where server is the name of the base server. If your OpenDeploy base server was named mars, then the base server log file path and name would be:

od-home/log/mars_odbase.log


Receiver Logging

To access the base server log from the user interface, follow these steps:

1. Select Servers > Manage Server to display the Manage Servers window.

2. Select the server whose base server log you want to view from the Selected Server list.

3. Click View Log. A separate browser window appears displaying the OpenDeploy Log Viewer window containing the base server log (Figure 3).

Figure 2: Base Server Log

Receiver Logging

All activities concerning an OpenDeploy receiver are written to the receiver log. Receiver log entries include information on:

Starting up OpenDeploy services and daemons

Receiving deployments

Reviewing the receiver log is an effective method of determining the activities of your OpenDeploy receiver, and of troubleshooting problems.

By default, the log file resides in the following location:

od-home/(od-instance)/log/server_odrcvr.log

where server is the name of the receiver. If your OpenDeploy receiver was named venus, then the receiver log file path and name would be:

od-home/log/venus_odrcvr.log

255

Logging

You can view the receiver log from the OpenDeploy user interface in the same manner as for the base server log. See “Base Server Logging” on page 254 for more information.

Macro Deployment Logging

The macro deployment logs write entries on every aspect of a deployment each time it is run. There are two macro deployment logs, one for the source (the source macro deployment log) and one for the target (the receiver macro deployment log). If the deployment is configured as a fan-out deployment with multiple target, the macro deployment log will have entries written for each source/target pairing. Each new running of a deployment causes a new set of log entries to be appended onto the file, so you can review the history of the deployment over a period of time.

Macro deployment log entries include information on:

Whether or not deployments to each target were successful.

Time the deployments took.

Reviewing the macro deployment log is a way to determine how a particular deployment functions, and to troubleshoot problems with that deployment. Here is an example of macro deployment log entries:

NG: 2001-11-28 13:06:12 PST GMT-08:00 internalDepName=.monthly.MYDEFINITIONNAME.jmoorebw2kENG: 2001-11-28 13:06:12 PST GMT-08:00 Got converted config for .monthly.MYDEFINITIONNAME.jmoorebw2kENG: 2001-11-28 13:06:12 PST GMT-08:00 Waiting for 2 children to complete phasesENG: 2001-11-28 13:06:12 PST GMT-08:00 All 2 children completed their phasesENG: 2001-11-28 13:06:12 PST GMT-08:00 Deployment[monthly] Elapsed Time=120 msENG: 2001-11-28 13:06:12 PST GMT-08:00 End logfile [C:\Interwoven\OpenDeployNG\log\src.monthly.log]

Source Macro Deployment Log

The source macro deployment log file contains log entries for a deployment where the OpenDeploy base server is the sender.

The source macro log by default resides in the following location:

od-home/(od-instance)/log/src.deployment.log

where deployment is the name of the deployment configuration. If your deployment was named monthly, then the source macro deployment log file path and name would be:

od-home/log/src.monthly.log


Macro Deployment Logging

To access the source macro deployment log from the user interface, follow these steps:

1. Select Deployments > View Deployments to display the Source Deployments window.

2. Select the server containing the deployment whose source macro deployment log you want to view from the Selected Server list.

3. Select Sending from the View list. All the deployments that the server sends are dis-played in a table.

4. Click View Log for the deployment whose source macro deployment log you want to view. A separate browser window appears displaying the OpenDeploy Log Viewer win-dow containing the source macro deployment log (Figure 3).

Figure 3: Source Macro Deployment Log

Receiver Macro Deployment Log

The receiver macro deployment log provides a similar service for OpenDeploy servers receiving deployments as the source macro deployment log does for sending servers. The receiver macro deployment log contains macro-type entries for the deployments received by the server.

A separate receiver macro log is generated anytime the combination of deployment name, definition name, and logical target name is unique. For example, if a deployment has three separate definitions all pointed at the same target, three separate receiver macro log files will be generated on the server receiving the deployment.

257

Logging

The receiver macro log by default resides in the following location:

od-home/(od-instance)/log/rcv.deployment.definition.target-server.log




target-server — the logical name of the target receiving a deployment as it appears in the nodes configuration file of the sending base server.

If your deployment was named monthly and the definition was named corporate, and the target’s logical name is jupiter, then the receiver macro deployment log file path and name would be:

od-home/log/rcv.monthly.corporate.jupiter.log

You must select Receiving from the View list in the Source Deployments window to access receiver macro deployment logs. See “Source Macro Deployment Log” on page 256 for more information.

Micro Deployment Logging

The micro deployment logs write entries for each source/target pair in a deployment. If the deployment includes only a single source and target, then one micro deployment log each is generated on the source and targets. If the deployment is a fan-out type with several targets, then a micro deployment log is generated for each of those targets.

The source will generate a separate micro deployment log (the source micro deployment log) for each target. Each target receiving the deployment generates its own log (the receiver micro deployment log). Each running of the deployment results in a new set of log entries to be appended onto the file, so you can review the history of the deployment over multiple runnings.

Micro deployment log entries include information on:

Contact made with the source or target

Directories and files successfully deployed

Directories and files that failed to deploy



Reviewing the micro deployment log is a way to determine how a particular deployment functions, and to troubleshoot problems with that source or target participating in a deployment. Here is an example of macro deployment log entries:

Directories deployed : 2 Files deployed : 34 Links deployed : 0Directories failed : 0 Files failed : 0 Links failed : 0Directories deleted : 0 Files deleted : 0 Links deleted : 0id=0 server: File Content transferred: 4647780 bytesid=0 server: [Wed Jun 13 10:29:55 2001] Deployment COMPLETED

Source Micro Deployment Log

The source micro deployment log contains log entries for the movement of files between the source and one target. If the deployment is a fan-out deploying to several targets, each source/target deployment will log its own micro deployment log.

The source micro log by default resides in the following location:

od-home/(od-instance)/log/src.deployment.definition.source-server.to.target-server.log





target-server — the logical name of the target server receiving a deployment as it appears in the nodes configuration file of the sending base server.

If your deployment was named monthly, the definition named corporate, your sending base server named mars, and the target named venus, then the source micro deployment log file name would be:

src.monthly.corporate.mars.to.venus.log

If your fan-out deployment had following targets:

venus

jupiter

then the sending base server would have the two corresponding source micro deployment log files:

src.monthly.corporate.mars.to.venus.log and

src.monthly.corporate.mars.to.jupiter.log

259

Logging

To access the source micro deployment log from the user interface, follow these steps:

1. Select Deployments > View Deployments to display the Source Deployment window.

2. Select the server containing the deployment whose source macro deployment log you want to view from the Selected Server list.

3. Select Sending from the View list. All the deployments that the base server sends are displayed in a table.

4. Click the link of the deployment whose source micro deployment log you want to view. The Details table appears at the bottom of the window, displaying a separate row for each target of the deployment.

5. Click View Log for the appropriate target. A separate browser window appears display-ing the OpenDeploy Log Viewer window containing the source micro deployment log (Figure 4).

Figure 4: Source Micro Deployment Log



Receiver Micro Deployment Log

The receiver micro deployment log provides a similar service for OpenDeploy servers receiving deployments as the source micro deployment log does for sending base servers. The receiver micro deployment log contains entries regarding the movement of files between the source and targets during the deployment.

The receiver micro log by default resides in the following location:

od-home/(od-instance)/log/rcv.deployment.definition.source-server.to.target-server.log





target-server — the logical name of the target receiving a deployment as it appears in the nodes configuration file of the sending base server.

If your deployment was named monthly, the definition named corporate, your sending base server named mars, and the target named venus, then the receiver micro deployment log file name would be:

rcv.monthly.corporate.mars.to.venus.log

You must select Receiving from the View list in the Source Deployments window to access micro deployment logs. See “Source Micro Deployment Log” on page 259 for more information.

261

Logging

Logging Levels

OpenDeploy provides the following logging level options:

Verbose — logs high level of detail on deployment events as they occur. This logging level is best suited for troubleshooting deployment problems or evaluating deployment performance. Verbose logging can create very large log files. This is the default logging level.

Normal — logs standard status and error messages. In most cases, this level of logging provides a sufficient amount of detail to meet your needs.

You can configure logging settings both on an OpenDeploy server basis, and on a deployment configuration basis. See “Logging Configuration Settings” on page 263 for more information.

Settings for deployment logging in the base server or receiver configuration can be overridden in the user interface, or by the deployment configuration. See “Logging Rules Hierarchy” on page 264 for more information.

Defining Logging Levels in the User Interface

Any time you manually start a deployment from the OpenDeploy user interface (Figure 5), you can specify the level of logging for that deployment. A level specified here automatically overrides any logging levels specified in the base server or deployment configurations.

Figure 5: Log Levels in the User Interface

Defining Logging Levels from the Command Line

You can specify the logging level for a deployment you start using the iwodcmd start command-line tool by including the -V option and the desired logging level. For example:

iwodcmd start deployment -V verbose or

iwodcmd start deployment -V normal

See “Running Deployments from the User Interface” on page 56 for more information on using iwodcmd start to run deployments.


Logging Configuration Settings

Logging Configuration Settings

You can configure logging in both base server and receiver configuration files (by default odbase.xml and odrcvr.xml) and in individual deployment configurations (for example, test.xml). Defining the logging settings in the configurations automates the logging rules that apply when a deployment runs. Logging settings are defined in the logRules element and its associated attributes.

Base Server and Receiver Configurations

In the base server and receiver configuration file, the logRules element appears as:

<logRules maxBytes="x" level="y" directory="z"/>

where x, y, and z are the values for the following attributes:

maxBytes — specifies the maximum size in bytes a log file is allowed to grow before the file is closed and OpenDeploy begins writing to a new file. This value is known as the rollover threshold. The default maxBytes value is 32 megabytes. You can specify different byte measurements in the value, including megabytes (mb), kilobytes (kb), and bytes (b). For example:

maxBytes="10mb" or

maxBytes="10000kb" or

maxBytes="10000000b"

indicates that the log file size can grow to 10 megabytes before OpenDeploy will close that log file and start a new one.

Ensure that you include the proper measurement indicator when setting the threshold size. If no recognizable size measurement is indicated, OpenDeploy uses its default value instead. For example, if the following value was specified:

maxBytes="10"

OpenDeploy would ignore that stated value and use the default value (32mb) instead.

If the unit of measure is present but unrecognized by OpenDeploy, the default value is used. For example, if the following value was specified:

maxBytes="1000x"

OpenDeploy would ignore this value and use the default value (32mb).

OpenDeploy will not honor a maxBytes value of less than 100 kilobytes (100kb). For example, if the following value was specified:

maxBytes="50kb"

OpenDeploy would ignore this value and use the default value (32mb) instead.

See “Log File Size Management” on page 265 for more information on rollover threshold.

263

Logging

level – indicates the level and type of logging OpenDeploy will perform.

verbose — logs high level of detail on deployment events as they occur. This logging level is best suited for troubleshooting deployment problems or evaluating deployment performance. Verbose logging can create very large log files. This is the default logging level.

normal — logs standard status and error messages. In most cases, this level of logging provides a sufficient amount of detail to meet your needs.

directory (base server and receiver configuration only) — specifies the absolute path directory location for log files. The default location is:

od-home/(od-instance)/log

Deployment Configurations

The logRules element functions the same in a deployment configuration as it does in a base server or receiver configuration file, except that the directory attribute is not present. For example:

<logRules maxBytes="10mb" level="normal"/>

You can only specify an alternative log file home in the base server or receiver configuration file. Logging settings for macro and micro deployment logs in a deployment configuration will override logging settings in the base server or receiver configuration.

Logging Rules Hierarchy

The following logging rules hierarchy apply to logging rules:

Base Server and Receiver Logging

The logging levels for the base server and receiver logs are specified in their associated configurations. The level of logging is defined as the value of the level attribute in the logRules element. Logging levels for this type of logging cannot be overridden. If the logRules element or any of its attributes are absent from the base server or receiver configuration, OpenDeploy will use the following default settings:

level — verbose

maxBytes — 32 mb

directory — od-home/(od-instance)/log


Log File Size Management

Macro and Micro Deployment Logging

The following hierarchy applies to the logging verbosity and maximum file size for deployment macro and micro logs:

Logging levels specified in the OpenDeploy user interface or the iwodcmd start command-line tool take precedence.

If the previous parameters are not specified, logging settings in the deployment configuration take precedence.

If neither of the previous parameters are specified, logging settings in the base server and receiver files take precedence.

If no other parameters are specified, OpenDeploy will use its default logging settings. See “Logging Configuration Settings” on page 263 for more information.

If there are any syntax errors in the specified maximum bytes value, such as a unit of measurement being absent or unreadable, OpenDeploy will use its default values for these circumstances. See “Logging Configuration Settings” on page 263 for more information.

Log File Size Management

Log files can grow large quickly, especially with large or numerous deployments. Using verbose logging (the default logging level) can also generate large log files. You should determine how much storage space to devote to log files before setting the logging type. OpenDeploy uses a log file rollover threshold feature to determine the maximum size a single log file can grow before that file is closed to new log entries and a new log file is generated.

The deployment macro logs for the source and the target are linked for rolling over. When the source’s macro log file requires being rolled over because it has met or exceeded its rollover threshold, the corresponding deployment macro log on the receiving server will also be rolled over, even if it has not reached its rollover limit. The source base server determines when a rollover is required.

The deployment micro logs are rolled over in a manner similar to that of macro logs. The source base server determines when a log file rollover must occur, and both the source and target micro logs are rolled over together. If a deployment is a fan-out type that includes multiple source/target pairs, the logs of each source/target pair are rolled over independent of other target-source pairs.

265

Logging

Rollover Threshold Size Determination

The threshold size of the log file is specified in the logRules element’s maxBytes attribute in the base server and receiver configurations files, and in the deployment configurations. If that value is not specified, or if the element is not defined in the configuration, OpenDeploy will look to the same element in the base server configuration file for logging information. If that information is still not present, OpenDeploy will use the default size of 32 MB. See “Logging Configuration Settings” on page 263 for more information.

Rolled Over Log File Naming

OpenDeploy will roll over a log file when it detects the file size exceeds its specified rollover size as indicated by its maxBytes attribute value. A serial naming convention is used to indicate the order of the archived log files. OpenDeploy uses a counter file (counter.cnt) to manage the generation of log archive files. Do not move or delete the counter file from the log directory.

When the log file is rolled over, that log’s file name is appended with a four-digit extension. This extension starts at 0001 and increases by 1 each time the same log is rolled over. Each log has a separate counter to keep track of rollovers. OpenDeploy subsequently creates a new log file with the original log file name and will start writing log entries to it. For example, if the following log file:

src.monthly.log

reached its rollover threshold level, OpenDeploy would close this file to further entries and subsequently archive it by adding an appropriate four-digit suffix:

src.monthly.log1234

In the following example, the log file src.single.mars.to.venus.log has been archived four times:

4669 Jun 6 10:49 src.single.mars.to.venus.log (current log)5 Jun 6 10:49 src.single.mars.to.venus.log.cnt (counter)3877 May 15 15:40 src.single.mars.to.venus.log0001 (first archive)2126 May 15 15:40 src.single.mars.to.venus.log0002 (second archive)2126 May 15 15:42 src.single.mars.to.venus.log0003 (third archive)3901 May 23 13:39 src.single.mars.to.venus.log0004 (fourth archive)

When the log rollover extension reaches 9999, the next time it rolls the log over, it will reset to 0001, followed by 0002 and so forth. If the log file with suffix 0001 already exists, that file will be overwritten by the new one as the extension resets. If you want to preserve old log files that are at risk of being overwritten, you should move them to another location.


Log File Recovery

Log File Recovery

The following sections explain log file recovery in OpenDeploy.

Base Server and Receiver Log Files

If the OpenDeploy base server or receiver log file is deleted, OpenDeploy will detect that it is missing and create a new log when one of the following event occurs:

When you start a deployment manually from the OpenDeploy user interface or using the iwodcmd start command line tool, or if a scheduled deployment is run.

When you refresh the server through the OpenDeploy user interface of the iwodcmd serverreset command-line tool. If the OpenDeploy base server or receiver configuration files have not been changed, this is a convenient way to generate new server log files if the existing ones become lost or damaged.

When any of the following security related events occur on the OpenDeploy server:

The list of users in a role is viewed.

A user is added or removed from a role.

A deployment is added or removed from an user in the od-user role.

A user is denied access to an OpenDeploy function.

When the OpenDeploy server is restarted after having been stopped.

Deployment Log Files

OpenDeploy will automatically generate new deployment macro and micro log files on both the source and receiver servers any time existing deployment log files are not detected. If a deployment log file is lost or damaged while that deployment is in progress, no recovery is possible. However, because deployments are logged on both the sending and receiving servers, you can view the remaining logs.

267

Logging

Administration Server Logging

The administration server maintains the following log files:

hostname_database.log — logs messages related to loading of drivers and connecting to the databases used for reporting and for database deployments.

hostname_subscriber.log — logs subscriber errors and warnings for reporting.

hostname_adminServerReporting.log — Logs general status, warnings, and errors related to event reporting.

hostname_odadmin_servletd.log (Windows) or odadmin_servletd.log (UNIX) — logs servletd status and errors.

odAdminServer.log — logs debug messages for administration server.

localhost_log.YYYY_MM_DD.txt — logs messages related to servletd startup and shutdown. A new log is created each day the adminserver is shutdown or started.

These logs reside in the following location:

admin-home/odadmin/log

Reporting Logging

There are several log files associated with the OpenDeploy reporting feature. These log files, their locations, and configurations are described in Chapter 8, “Reporting” under the following sections:

Server reporting log — see “Logging” on page 275.

Reporting logs associated with the administration server — see “Logging” on page 277.


Adapter Logging

Adapter Logging

Delivery and payload adapters used with OpenDeploy have their own log files. By default, these files reside in the following directory:

od-home/log

Specifying an alternate log file location for the base server and receiver configuration files also redirects the adapter log files to that same location. See “Log File Location” on page 251 for more information.

The rollover threshold level for adapter log files is fixed at 32 MB. The rollover threshold behavior is similar to that of the other log files. See “Log File Size Management” on page 265 for more information.

Adapter log files use the following file name syntax:

adp.adapterName.legName.log

where adapterName is an abbreviated name for the adapter, and legName is the particular leg of the deployment. See “Micro Deployment Logging” on page 258 for more information on how the legName value is composed.

The following table lists the adapter names used in the adapter log file naming:

Adapter Adapter Name

BEA bulk loader bbl

ClearCase cc

CVS cvs

Email email

Example delivery exmpld

FTP ftp

Generic delivery gen

Microsoft COM mscom

Microsoft Global Assembly Cache msgac

Microsoft Application Center msac

Microsoft Visual Source Save (VSS) vss

MKS mks

PVCS pvcs

WebLogic Application server wlas

WebSphere Application server wsas

WebSphere Portal target wspsd

269

Logging

For example, the log file for the BEA bulk loader might be the following:

adp.bbl.deploy.def.src.to.tgt.log

If you upgrade to this release from OpenDeploy 6.0.2 or earlier, the legacy log names for those adapters:

legName.legacyAdapterName.log

will remain unchanged. However, following the upgrade, those adapters listed in the table will start generating new log files using the file naming syntax described here.

WebSphere Portal source wspsp

Adapter Adapter Name


Chapter 8

Reporting

Each OpenDeploy base server and receiver installation includes a reporting component used to publish events to a reporting server, which is installed as part of the administration package. Events sent by an OpenDeploy server to the reporting server are stored in a user-defined database. These events can subsequently be accessed by the administration server for viewing within the browser-based user interface.

Reports generated by an OpenDeploy server are durable. If the reporting server is temporarily unavailable, the OpenDeploy server retains the events until they can be successfully transferred after the reporting server goes back into service.

OpenDeploy provides the following reporting features available through the browser-based user interface:

Custom reports — reports that allow you to apply a search criteria based on deployment name, deployment owner, timeframe, and other factors.

DAS custom reports — reports, similar to custom reports, that give indications of database updates resulting from TeamSite event triggers.

ControlHub custom reports — reports, similar to custom reports, that give indications of ControlHub activity. These reports are only available when using OpenDeploy in conjunction with ControlHub.

SQL query reports — reports where you compose the structure of the report yourself using SQL. You can also apply the search criteria feature available in custom reports to your SQL query reports.

Quick reports — queries of either type that are saved and available for running at any time without having to perform any additional configuration.

271

Reporting


Each OpenDeploy server participating in reporting must have the following:

The eventReporting element must be enabled in the server configuration file.

The server reporting configuration file must be fully configured for reporting.

Server Configuration File

Each OpenDeploy base server (by default odbase.xml) or receiver (by default odrcvr.xml) configuration file includes the eventReporting element, which enables the server’s ability to use the reporting feature and specifies server reporting configuration file:

<deployServerConfiguration>...<eventReportingenabled="yes"cfgPath="C:\Interwoven\OpenDeployNG\etc\eventReportingConfig.xml"/>

</deployServerConfiguration>

Refer to Chapter 3, “Server and Host Configuration”on page 73 in the OpenDeploy Installation Guide for more information.

Enabling Reporting

You must enable the reporting feature in the server configuration file by giving the eventReporting element’s enabled attribute a value of yes. If the enabled attribute has a value of no, or if the eventReporting element is missing from the server configuration, reporting is not enabled on that server.

During the base server and receiver software installation, you are prompted whether to enable the reporting feature or not. Typically, reporting is intended to capture events from the original sending server, and perhaps next-tier base servers, but not necessarily end point targets. Therefore, the default installation for the base server software is with reporting enabled, while the default installation for receiver software is with reporting disabled.

Path to Server Reporting Configuration File

The eventReporting element’s cfgPath attribute value specifies the path to the reporting configuration file (by default eventReportingConfig.xml). The default path is the following:

od-home/(od-instance)/etc/eventReportingConfig.xml

but you can name and locate the file anywhere on your server host’s file system, as long as that name and location are reflected in the cfgPath attribute. The eventReporting element is included in the base server configuration file by default, automatically enabling the feature. To disable reporting, you must comment out or delete the eventReporting element from the base server configuration file.



Server Reporting Configuration File

Reporting is a highly flexible feature that requires its own configuration file on each OpenDeploy server. The server’s reporting configuration file (by default eventReportingConfig.xml) contains the elements and attributes that determine the functionality of the reporting feature on that server.

The server reporting configuration file contains various elements and attributes that manages the server’s ability to use the reporting feature. The following sections describes those elements and attributes you typically would want to configure, such as logging. Other elements and attributes require no user configuration and are not covered. To obtain information on all elements and attributes contained in the server reporting configuration file, refer to Chapter 12, “Reporting Server Configuration DTD” on page 225 in the OpenDeploy Reference.

The following page displays a sample server reporting configuration file.

273

Reporting

<eventReportingConfiguration><log name="openDeployPublisherLog"path="MYOPENDEPLOYINST/log/MYHOSTINSTNAME_publisher.log" append="true"/>

<process name="OpenJMS" startCommand="MYOPENDEPLOYSHORT/jre/bin/java -Xmx256M -Xms64M -Dopenjms.home=MYOPENDEPLOYSHORT/openjms -Djava.security.manager -Djava.security.policy=MYOPENDEPLOYSHORT/openjms/config/openjms.policy -Djava.rmi.server.codebase=file:MYOPENDEPLOYSHORT/openjms/lib/openjms-client-0.7.6.1.jar -Djava.rmi.server.useCodebaseOnly=true ${OPENJMS_RMI_PORTS} -classpath ${OPENJMS_CP} org.exolab.jms.server.JmsServer -config MYOPENDEPLOYINSTSHORT/etc/jmsConfig.xml" stopCommand="MYOPENDEPLOYSHORT/jre/bin/java -Dopenjms.home=MYOPENDEPLOYSHORT/openjms -Djava.security.manager -Djava.security.policy=MYOPENDEPLOYSHORT/openjm/config/openjms.policy ${OPENJMS_RMI_PORTS} -classpath ${OPENJMS_CP}org.exolab.jms.tools.admin.AdminMgr -config MYOPENDEPLOYINSTSHORT/etc/jmsConfig.xml -stopServer" startDir="MYOPENDEPLOY/openjms"><environment name="OPENJMS_CP" value="MYOPENDEPLOYSHORT/lib/

hsqldb.jar"/><environment name="OPENJMS_CP" value="${OPENJMS_CP}:

MYOPENDEPLOYSHORT/openjms/lib/openjms-0.7.6.1.jar"/><environment name="OPENJMS_RMI_PORTS" value="-DRmiPort1=${JMS_RMI1}

-DRmiPort2=${JMS_RMI2} -DRmiPort3=${JMS_RMI3} -DRmiPort4=${JMS_RMI4} -DRmiPort5=${JMS_RMI5} -DRmiPort6=${JMS_RMI6} -DRmiPort7=${JMS_RMI7} -DRmiPort8=${JMS_RMI8}"/>

</process><jndiContext initialContextFactory="org.exolab.jms.jndi.InitialContextFactory" url="tcp://MYHOSTNAME:MYJMSJNDIPORT/"classpath="MYOPENDEPLOYSHORT/openjms/lib/openjms-client-0.7.6.1.jar:MYOPENDEPLOYSHORT/openjms/lib/exolabcore-0.3.7.jar"><connectionFactory factoryName="JmsTopicConnectionFactory">

<connection exceptionListener="com.interwoven.deploy.event.TExceptionListener"><property name="useLog" value="openDeployPublisherLog"/><session transactional="false"

acknowledgeMode="CLIENT_ACKNOWLEDGE"><publisher name="openDeployPublisher" topic="Interwoven"/>

</session></connection>

</connectionFactory></jndiContext>

</eventReportingConfiguration>


File Location

The server reporting configuration file resides in the following location:

od-home/(od-instance)/etc/eventReportingConfig.xml

You have the option of renaming this file. However, if you rename it, you must also update the file reference in the eventReporting element’s cfgPath attribute value in the server’s base server or receiver configuration file. See “Server Configuration File” on page 272 for more information.

The server reporting configuration file is installed with default settings allowing you to use the reporting feature with no additional modification required. However, as you use the reporting feature, you may want to change the settings to customize the reporting to your enterprise’s particular requirements. The following sections describe different modifications you can make to the file.

Logging

The reporting feature generates it own log file. By default, this file resides in the following location:

od-home/(od-instance)/log/publisher.log

You can configure the log entries and file location in the reporting configuration file through the log element:

<eventReportingConfiguration><log name="reportingLog"path="C:\Interwoven\OpenDeployNG\eventlog\publisher.log"append="false"/>

...</eventReportingConfiguration>

The log element contains the following associated attributes:

name — denotes the unique name of the log element. For example:

name="reportingLog"

path — specify the absolute path to the log file. For example:

path="od-home/eventlog/publisher.log"

append — specify whether the file should be appended to (true) or truncated (false). If the value is true, new log entries are appended to the end of the existing log file. If the value is false, when OpenDeploy is started, the log file’s existing entries are deleted, and replaced by new ones. The default value is true.

275

Reporting

Administration Server Configuration for Reporting

The administration server contains a reporting management configuration file for use in displaying generated reports in the browser-based user interface.

<odReportingConfiguration hostName="ODSVR_HOSTNAME">

<log name="openDeploySubscriberLog" path="ADMINSERVER_OD_DIR/log/MYHOSTNAME_subscriber.log" append="true"/> <log name="databaseLog" path="ADMINSERVER_OD_DIR/log/MYHOSTNAME_database.log" append="true"/>

<database name="ReportingDB" className="org.hsqldb.jdbcDriver" connectionString="jdbc:hsqldb:ADMINSERVER_OD_DIR/db/eventReporting.db"> <property name="user" value="sa" /> <property name="password" value="" /> </database>

 <odNode host="ODSVR_HOSTNAME" port="JMSRMIPORT"/>

</odReportingConfiguration>

Upon installation, this configuration file requires little or no modification to work. However, for production use it is strongly recommended that you use your own JDBC-compliant database rather than the demonstration database that is included. Refer to the OpenDeploy Release Notes for a list of certified databases.

You must also modify the configuration file to select additional servers from which to receive reporting information.

File Location

The reporting management configuration file resides in the following location:

admin-home/odadmin/config/adminEventReportingConfig.xml

This is a fixed file that cannot be renamed or relocated.


Connection Management

The odReportingConfiguration element is the root element of the reporting management configuration file.

<odReportingConfiguration hostName="saturn" restartInterval="150000"roundRobbin="true">...


This element contains the following attributes that are used to specify information related to the reporting server’s connection:

hostName — specify the resolvable name or the IP address of the current host. This attribute value distinguishes this subscriber from others. Do not assign a value of localhost or 127.0.0.1 if you plan to connect other OpenDeploy reporting nodes.

hostPort — (optional) specify the host’s port used by OpenDeploy. This attribute is optional, and is only honored if the publisher attribute value is true (see below).

publisher — specify whether (true) or not (false) this reporting management configuration can publish reports. Default value is false. If the configuration is running on the administration server, it is not necessary to give this attribute the value true.

restartInterval — specify the time interval (in milliseconds) between retries of failed connections. The default value is 300000 (300 seconds or 5 minutes).

roundRobbin — specify whether to pass between connections (true) or use them all simultaneously (false). Default value is false.

Logging

The administration server maintains the following log files associated with the reporting feature, where host is the host of the administration server software:

host_adminEventReporting.log — logs messages from the overall reporting framework, such as startups, shutdowns and errors.

host_database.log — logs the JDBC driver activity. It logs any output from the JDBC database driver, either from the default Hyptersonic, or a user-specified DBMS driver.

host_subscriber — logs messages from the JMS message listener. It gets the messages from the OpenDeploy JMS server and places them into the DBMS.

By default, each of these log files reside in the following location:

admin-home/log

277

Reporting

You can configure the database and subscriber log files using log elements:

<odReportingConfiguration ...><log name="databaseLog"path="admin-home/log/mars_database.log"append="true"/>

<logname="openDeploySubscriberLog"path="admin-home/log/mars_subscriber.log"append="true"/>...


See “Logging” on page 275 for descriptions on logging behavior and descriptions of the attributes.

Sub-Process Commands

You can specify sub-process commands in the reporting management configuration file using the process element:

<odReportingConfiguration ...>...<process ...>...

</process...


The process element defines a series of sub-process command attributes associated with the reporting feature:

name — denotes the unique name of the process element.

startCommand — specifies the command-line tool used to start the sub-process. For example:

startCommand="/usr/bin/cat"

See java.lang.Runtime.exec() in the Java API documentation for more information.

stopCommand — specifies the command-line tool used to stop the sub-process. For example, if you had the following startCommand attribute value:

startCommand="/etc/init.d/lpd start"

You might specify the corresponding stopCommand attribute value:

stopCommand="/etc/init.d/lpd stop"

If a stopCommand value is not specified, the sub-process is destroyed.



startDir — specifies the directory to change to before starting the sub-process. For example:

startDir="/etc"

The default directory is the one you are currently in.

stdin — specifies the absolute path to a file from which to read input for the sub-process. For example:

stdin="passwd"

stdout — specifies the absolute path to a file in which to write the output of the sub-process. For example:

stdout="/export/home/jdoe/passwd.copy"

stderr — specifies the absolute path to a file in which to write the error output of the sub-process. For example:stderr="/export/home/jdoe/passwd.copy.err"

Environmental Variables

You can specify environmental variables that are passed on to the sub-commands using one or more environment elements within a process element.

<process ...><environment .../>

</process

The environment element contains the following attributes:

name — denotes the name of this environment variable. For example:

name="POLICY_FILE"

This value does not need not be unique, as environment elements are processed in the order they appear in the XML. Each occurrence supersedes any previous occurrences with the same name.

value — specify the value to set the environment variable to. For example:

value="od-home/openjms/src/etc/openjms.policy"

This value may contain references to Java system properties or to other environment elements that precede this one. For example:value="${OPENJMS_CP}${path.separator}${java.class.path}"

obscured — indicate whether (true) or not (false) the value attribute is encoded. Use the iwodpasscoder program to generate the encoded string. Refer to “iwodpasscoder” on page 40 in the OpenDeploy Reference for more information on this tool. Default value is false.

279

Reporting

Reporting Server Database

The reporting server requires database software to manage the reporting. By default, the reporting server software is installed with a Hypersonic database. However, this database is included for demonstration purposes and is not sufficiently powerful for most enterprise requirements. You are strongly encouraged to use your own JDBC-compliant database instead. Refer to the OpenDeploy Release Notes for a list of certified databases you can use.

ControlHub Events

When using OpenDeploy with ControlHub, ControlHub events are stored using the same database as is used for the OpenDeploy reporting server. If the default Hypersonic database is used, the ControlHub events are stored in the flat-file database openjms.db residing in the following location:

iw-home\eventsubsystem

This default flat-file database is included for demonstration purposes and is not sufficiently powerful for most enterprise requirements. Using your own JDBC-compliant database for your reporting server will also provide the ControlHub events with a sufficiently powerful database.

Using Your Own Database

By default, OpenDeploy installs the Hypersonic database for use with the reporting server software. Upon installation, the Hypersonic database is initialized and ready to use. However, this database is included for demonstration purposes, and is probably not sufficiently powerful for most enterprise reporting requirements.

You can configure the reporting server to use your own database. Several databases have been certified for use with the reporting server software, and customized initialization scripts for those databases are included with the OpenDeploy software. Refer to the OpenDeploy Release Notes for a list of those certified databases and initialization scripts.

You are responsible for obtaining the appropriate JDBC driver. Some drivers are included in the OpenDeploy administration package installation, residing in the following location:

admin-home/odadmin/drivers

If the driver you need is not there, check the Web site associated with your database’s vendor.

Alternatively, you can use a non-certified JDBC-compliant database with the reporting server. However, you must provide your own initialization script for that database. You can use one of the initialization scripts provided as a starting basis to develop your own initialization script.

Note: If you are using OpenDeploy in conjunction with ControlHub, the process for using your own database is different. The section after this one addresses that topic.


To configure your own reporting server database, follow these steps:

1. Obtain the appropriate JDBC drivers. These are typically available from your database vendor’s Web site.

2. Stop the administration server service or daemon. See “Stopping OpenDeploy” on page 21 for more information.

3. Open the reporting management configuration file (adminEventReportingConfig.xml) using your favorite text or XML editor. The file resides in the following location:


4. Comment out the database element and its associated attributes that is currently in use, and uncomment one of the database elements provided for the database you want to use. For example, by default, the following database element is used:

<database name="ReportingDB" className="org.hsqldb.jdbcDriver"connectionString="jdbc:hsqldb:C:/Interwoven/AdminServer/odadmin/db/eventReporting.db">

<property name="user" value="sa"/><property name="password" value=""/>

</database>

If you wanted to use IBM DB2, you would comment out the default (Hypersonic) database element, and uncomment the following database element:



5. Replace the parameter variables in the database element you want to use, such as USERNAME and PASSWD with the appropriate actual values. See “Configuring Your Data-base” on page 285 for more information.


7. Copy the JDBC driver .jar files associated with your database to the following loca-tion:

admin-home/httpd/iwwebapps/opendeploy/WEB-INF/lib

8. Use your database's tools to create and initialize the tables.

If you are using a certified database, you can run the initialization scripts provided with OpenDeploy. Refer to the OpenDeploy Release Notes for a list of the certified databases and the associated initialization scripts.

281

Reporting

If you are using a non-certified JDBC-compliant database, you must create your own initialization script. Refer to Chapter 20, “Reporting Server Database Schema” on page 317 in the OpenDeploy Reference for a listing and description of the database schema to which the initialization script initializes. A file containing this schema also resides at the following location:

admin-home/db/odreportschemas.txt

You also can use the following files as guides:

admin-home/db/ODEvents.sql — defines the reporting schema. This is a base version that is not customized for any particular database.

admin-home/db/quickreportlist.sql — contains the definitions of the default quick reports. This is a base version that is not customized for any particular database.

9. Navigate to the following location:

admin-home/odadmin/db

10. Enter the following command at the prompt:

Windows — iwoddbtool.bat -sql quickreportslist_DBMS.sql

UNIX — ./iwoddbtool -sql quickreportslist_DBMS.sql

where DBMS is the correct abbreviation for the database you are using. Refer to “Database Abbreviations” on page 15 in the OpenDeploy Release Notes for a list of these abbreviations.

11. Restart the administration server service or daemon. See “Starting OpenDeploy” on page 17 for more information.

Using Your Own Database When Using ControlHub

Configuring the reporting server to use your own database when running OpenDeploy with ControlHub is different than for running OpenDeploy as a standalone product. See “Using Your Own Database” on page 280 for background information and guidance on using your own database with OpenDeploy.

Several steps during this procedure require you to specify a particular abbreviation for the database you are using. Refer to “Database Abbreviations” on page 15 in the OpenDeploy Release Notes for a list of these abbreviations.

To configure your own reporting server database when using OpenDeploy with ControlHub, follow these steps:

1. Obtain the appropriate JDBC drivers. These are typically available from your database vendor’s Web site.

2. Stop the ControlHub reporting feature by entering the following command at the prompt:

Windows — net stop iwtsreport



UNIX — iw-home/tsreport/bin/tsreport.sh stop

where iw-home is the location where the ControlHub resides.

3. Stop the iwservletd program by entering the following command at the prompt:

Windows — net stop iwservletd

UNIX — /etc/init.d/iwservletd stop

4. Copy all required JDBC drivers for you database to the following location:iw-home/tsreport/lib

5. Delete the tsreport.xml file, which resides in the following location:

iw-home/tsreport/conf

6. Rename the tsreport.xml.example file, which resides in the following location:


to tsreport.xml.

7. Open the following file using your favorite text editor:

Windows — alldbschema.bat

UNIX — alldbschema.sh

8. Update the name of the DBMS-schema.xml file references (by default hsqldb-schema.xml) where DBMS is the correct abbreviation for the database you are using. Refer to “Database Abbreviations” on page 15 in the OpenDeploy Release Notes for a list of these abbreviations.

9. Update all -db* parameters variable (such as -dbuser, -dbpasswd, -dbserver, and -dbname) with the actual connection information appropriate to your database. For example -dbuser jdoe and -dbserver mars.





12. Open the reporting management configuration file (adminEventReportingConfig.xml) file, which resides in the following location:


using your favorite text or XML editor.

13. Comment out the database element and its associated attributes that is currently in use, and uncomment one of the database elements provided for the database you want to use. For example, by default, the following database element is used:

<database name="ReportingDB" className="org.hsqldb.jdbcDriver"connectionString="jdbc:hsqldb:C:/Interwoven/AdminServer/odadmin/db/eventReporting.db">

283

Reporting

<property name="user" value="sa"/><property name="password" value=""/>

</database>

If you wanted to use IBM DB2, you would comment out the default (Hypersonic) database element, and uncomment the following database element:



14. Replace the parameter variables in the database element you want to use, such as USERNAME and PASSWD with the appropriate actual values. See “Configuring Your Data-base” on page 285 for more information.


16. Copy the JDBC driver .jar files associated with your database to the following loca-tion:

admin-home/httpd/iwwebapps/opendeploy/WEB-INF/lib

17. Use your database's tools to create and initialize the tables.

If you are using a certified database, you can run the initialization scripts provided with OpenDeploy. Refer to the OpenDeploy Release Notes for a list of the certified databases and the associated initialization scripts.

If you are using a non-certified JDBC-compliant database, you must create your own initialization script. Refer to Chapter 20, “Reporting Server Database Schema” on page 317 in the OpenDeploy Reference for a listing and description of the database schema to which the initialization script initializes. A file containing this schema also resides at the following location:

admin-home/db/odreportschemas.txt

You also can use the following files as guides:

admin-home/db/ODEvents.sql — defines the reporting schema. This is a base version that is not customized for any particular database.

admin-home/db/quickreportlist.sql — contains the definitions of the default quick reports. This is a base version that is not customized for any particular database.



Windows — iwoddbtool.bat -sql ODEvents_DBMS.sql

UNIX — ./iwoddbtool -sql ODEvents_DBMS.sql



Windows — iwoddbtool.bat -sql quickreportslist_DBMS.sql

UNIX — ./iwoddbtool -sql quickreportslist_DBMS.sql


21. Restart the iwservletd program by entering the following command at the prompt:

Windows — net start iwservletd

UNIX — /etc/init.d/iwservletd start

22. Restart the ControlHub reporting feature by entering the following command at the prompt:

Windows — net start iwtsreport

UNIX — iw-home/tsreport/bin/tsreport.sh start

Configuring Your Database

In the reporting management configuration file, the database is specified by the database element:

<odReportingConfiguration ...>...<database

name="ReportingDB"className="org.hsqldb.jdbcDriver"connectionString="jdbc:hsqldb:C:\Interwoven\AdminServer\db\

eventReporting.db"><property name="user" value="sa"/><property name="password" value="123ABC"/>

</database>...

<odReportingConfiguration>

The database element contains the following required attributes that you must configure:

name — this value is fixed as ReportingDB.

className — specify the class name of the JDBC driver class to load. For example:

className="org.hsqldb.jdbcDriver"

285

Reporting

connectionString — specifies the JDBC connection string (URL) to use to connect to the database. For example:

connectionString="jdbc:hsqldb:C:\Interwoven\AdminServer\db\eventReporting.db"

Refer to the Java API documentation on the Sun Web site on the java.sql.DriverManager.getConnection() method for more information regarding the connection string format.

Specifying the Database User Name and Password

Depending on the type of database you are using, you might need to configure a database user name and password. You can specify both of these items using property elements within the database element, for example:

<database ...><property name="user" value="sa"/><property name="password" value="123ABC" obscured="true"/>

</database>

The property element resides within the database element, and has the following attributes:

name — specifies the classification of the property element, for example:

name="user" or

name="password"

value — specifies the value, for example:

value="sa" or value="123ABC"

obscured — indicate whether (true) or not (false) the value attribute is encoded. Use the iwodpasscoder program to generate the encoded string. Refer to “iwodpasscoder” on page 40 in the OpenDeploy Reference for more information on this tool. Default value is false.

The need for a user name and password is JDBC driver dependent. Any property elements specified are passed to the JDBC driver as properties that it may use for establishing the connection or setting driver options. Only one user name and password is supported for the database. Refer to your database documentation to determine whether a user name and password are required.

Resetting the Database

Resetting the database clears it of existing reporting information and allows the reporting feature to have a fresh start. You can reset your reporting database, regardless of the type, through the OpenDeploy user interface by systematically deleting all event reporting data and saved report queries.



To reset your reporting database, follow these steps:

1. Access the Report Maintenance window and delete the event reporting data. See “Managing Report Data” on page 315 for more information on this procedure.

2. Access the Edit Quick Report window and delete each saved quick report. See “Delet-ing Entries” on page 314 for more information on this procedure.

Resetting the Hypersonic Database

In some cases, for example during demonstrations of the reporting feature, you might want to reset the default Hypersonic database. You can reset the Hypersonic database using the method described in “Resetting the Database” on page 286. However, if the demonstration database has been corrupted, you should perform the more comprehensive resetting procedure described below.

Note: If you are using OpenDeploy in conjunction with ControlHub, the process for resetting the Hypersonic database is different. The section after this one addresses that topic.

To reset the Hypersonic database, follow these steps:

1. Stop the administration server service or daemon. See “Stopping OpenDeploy” on page 21 for more information.



3. Delete the eventReporting.db.* files.


Windows — iwoddbtool.bat -sql ODEvents_hSql.sql

UNIX — ./iwoddbtool -sql ODEvents_hSql.sql


Windows — iwoddbtool.bat -sql quickreportlist_hSql.sql

UNIX — ./iwoddbtool -sql quickreportlist_hSql.sql

6. Restart the administration server service or daemon. See “Starting OpenDeploy” on page 17 for more information.

287

Reporting

Resetting the Hypersonic Database When Using ControlHub

Resetting the Hypersonic database when running OpenDeploy with ControlHub is different than for running OpenDeploy as a standalone product.

To reset the Hypersonic database when using OpenDeploy with ControlHub, follow these steps:

1. Stop the ControlHub reporting feature by entering the following command at the prompt:

Windows — net stop iwtsreport

UNIX — iw-home/tsreport/bin/tsreport.sh stop

where iw-home is the location where the ControlHub resides.

2. Stop the iwservletd program by entering the following command at the prompt:

Windows — net stop iwservletd

UNIX — iw-home/private/bin/iwuiboot stop

3. Stop the Hypersonic database by entering the following command at the prompt:

Windows — net stop iw-hsqldbd

UNIX — /etc/init.d/hsqldb stop

4. Delete the contents of the following directory:

iw-home/hsqldb/data

5. Restart the Hypersonic database by entering the following command at the prompt:

Windows — net start iw-hsqldbd

UNIX — /etc/init.d/hsqldb start

6. Delete the tsreport.xml file, which resides in the following location:


7. Rename the tsreport.xml.example file, which resides in the following location:


to tsreport.xml.


iw-home/tsreport

9. Rename the following file to a name of your own choosing, keeping the .bat or .sh extension intact:



10. Open the renamed .bat or .sh file using your favorite text editor and replace the fol-lowing tags with the specified value:

[DBTYPE] — hsqldb



[DBUSER] — SA

[DBPASSWORD] — (leave blank)

[DBSERVER] — controlhub

[DBNAME] — (leave blank)

[DBPORT] — 9001


12. Enter the renamed .bat or .sh file at the prompt.




Windows — iwoddbtool.bat -sql ODEvents_hSql.sql

UNIX — ./iwoddbtool -sql ODEvents_hSql.sql


Windows — iwoddbtool.bat -sql quickreportlist_hSql.sql

UNIX — ./iwoddbtool -sql quickreportlist_hSql.sql

16. Restart the iwservletd program by entering the following command at the prompt:

Windows — net start iwservletd

UNIX — iwreset -ui

17. Restart the ControlHub reporting feature by entering the following command at the prompt:

Windows — net start iwtsreport

UNIX — iw-home/tsreport/bin/tsreport.sh start

Logging

The reporting server database maintains a log of activity. See “Logging” on page 277 for more information.

Upgrading From Standalone OpenDeploy to CPS When Using the Hypersonic Database

If your OpenDeploy server uses the default Hypersonic database, and you want to upgrade to Content Provisioning Solution 2.0 or later, you must first migrate the Hypersonic content manually using the methods described in this section.

Windows

To migrate your Hypersonic database content on a Windows host, follow these steps:

1. Stop the administration server.

2. Navigate to the following location:admin-home\odadmin\db

289

Reporting


iwoddbtool.bat -sql admin-home\odadmin\db\hSqldb-bak.sql

4. Create the following subdirectory:

hSqldbOD_ver

where OD_ver is your existing version of OpenDeploy. For example, hSqldb602.

5. Copy the following files:

eventReporting.db.*

into your new hSqldbOD_ver subdirectory.

6. Open the hSqldb-bak.script file using your favorite text editor.

7. Remove the following line from the file:CREATE USER SA PASSWORD "" ADMIN

and save and close the file.

8. Copy the hSqldb-bak.script file into the hSqldbOD_ver subdirectory.

9. Upgrade to CPS 2.0 and run it.

10. Navigate to the following location:admin-home/odadmin/db

11. Enter the following commands at the prompt:iwoddbtool.bat -sql dropODEvents_hSql.sqliwoddbtool.bat -sql hSqldbold_ver\hSqldb-bak.script

UNIX

To migrate your Hypersonic database content on a UNIX host, follow these steps:

1. Stop the administration server.



iwoddbtool -sql admin-home/odadmin/db/hSqldb-bak.sql

4. Create the following subdirectory:

hSqldbOD_ver

where OD_ver is your existing version of OpenDeploy. For example, hSqldb602.

5. Copy the following files:

eventReporting.db.*

into your new hSqldbOD_ver subdirectory.

6. Open the hSqldb-bak.script file using your favorite text editor.



7. Remove the following line from the file:

CREATE USER SA PASSWORD "" ADMIN

and save and close the file.

8. Copy the hSqldb-bak.script file into the hSqldbOD_ver subdirectory.

9. Upgrade to CPS 2.0 and run it.


11. Enter the following commands at the prompt:

./iwoddbtool -sql dropODEvents_hSql.sql

./iwoddbtool -sql hSqldbold_ver/hSqldb-bak.script

Upgrading Reporting Tables

If you are upgrading from OpenDeploy 5.6, 6.0, or 6.0.1 to this release, you must upgrade your reporting tables after completing the upgrade and restarting the host. This procedure is similar to initially setting up a third-party database, as described in “Using Your Own Database” on page 280. However, instead of running the two scripts to create and load the tables, you must run the following script, depending on the release from which you are upgrading:

OpenDeploy 5.6 — ODEvents-56-to-602_DBMS.sql

OpenDeploy 6.0 and 6.0.1 — ODEvents-60-to-602_DBMS.sql

where dbms is the abbreviation for one of the supported databases as they appear in the initialization scripts for certified databases. Refer to “Database Abbreviations” on page 15 in the OpenDeploy Release Notes to determine the abbreviation for your database.

If you upgrade your administration server, but do not upgrade your reporting tables, all write attempts to the database will fail. Reporting information and log errors will be written to the following log file:

admin-home/odadmin/log/server_subscriber.log

where server is the OpenDeploy server name.

291

Reporting

Upgrading the Default Reporting Database

You can upgrade the default Hypersonic reporting database from OpenDeploy 5.6 to the current release using one of the following methods:

Converting the existing database to the current version.

Deleting the old database and installing a fresh installation.

The following sections describe each method.

Fresh Installation on Windows

To perform a fresh installation of the Hypersonic reporting database on Windows, follow these steps:

1. Stop the administration server. See “Stopping OpenDeploy” on page 21 for more information.

2. Open a command prompt window and navigate to the following location:

admin-home\odadmin\db


del eventReporting.db.*

iwoddbtool -sql ODEvents_hSql.sql

iwoddbtool -sql quickreportlist_hSql.sql

Fresh Installation on UNIX

To perform a fresh installation of the Hypersonic reporting database on UNIX, follow these steps:





rm eventReporting.db.*

./iwoddbtool -sql ODEvents_hSql.sql

./iwoddbtool -sql quickreportlist_hSql.sql



Upgrading on Windows

To upgrade your legacy Hypersonic reporting database to the current release on Windows, follow these steps:


2. Open a command prompt window and navigate to the following location:

admin-home\odadmin\db


echo SHUTDOWN COMPACT; | iwoddbtool

4. Enter the following command at the prompt, depending on the OpenDeploy release from which you are upgrading:

OpenDeploy 5.6 — iwoddbtool -sql ODEvents-56-to-602_hSql.sql

OpenDeploy 6.0 and 6.0.1 — iwoddbtool -sql ODEvents-60-to-602_hSql.sql

Upgrading on UNIX

To upgrade your legacy Hypersonic reporting database to the current release on UNIX, follow these steps:




3. Enter the following command at the prompt:echo "SHUTDOWN COMPACT;" | ./iwoddbtool

4. Enter the following command at the prompt, depending on the OpenDeploy release from which you are upgrading:

OpenDeploy 5.6 — ./iwoddbtool -sql ODEvents-56-to-602_hSql.sql

OpenDeploy 6.0 and 6.0.1 — ./iwoddbtool -sql ODEvents-60-to-602_hSql.sql

293

Reporting

Adding Servers to the Reporting Environment

After installing the reporting server software as part of the administration package, you must configure the software to receive published events from each OpenDeploy server in the reporting environment.The reporting management configuration file (adminEventReportingConfig.xml) must contain an occurrence of the odNode element for each server:

<odReportingConfiguration ...>...<odNode host="mars" port="9172" version="6.0.2"/>


The odNode element has the following associated attributes:

host — specify the resolvable name or IP address of the host.

port — specify the port number used by the server. Note that for this release, the port attribute represents the JNDI port number (default value is 9172). For OpenDeploy 6.0.1 and earlier releases, the port attribute represented the RMI port number (default value is 9173).

version — specify the release number of the OpenDeploy server running on the host. For example:

version="6.0.0"

The default value is 5.6.0. If a later release of OpenDeploy is running on that node, that release number must be specified.

unsubscribed — (optional) indicate whether (true) or not (false) the server had been previously subscribed into the reporting environment and should now be unsubscribed. Unsubscribing cleans up resources which might not be released if the odNode element entry is removed. Default value is false.

debug — (optional) indicate whether (true) or not (false) to log each event received. Default value is false.

Any additional servers you want to include in the reporting environment would need to have their own associated odNode elements added to the reporting management configuration file in the same manner. For example:

<odReportingConfiguration ...>...<odNode host="mars" port="9173" version="6.0.1"/><odNode host="venus" port="9174" version="6.0.0"/><odNode host="jupiter" port="9175"/>




Using a Third-Party Database for Store-and Forward System

The internal OpenDeploy reporting message store-and-forward system can begin to use a large percentage of CPU time or can fail under one or more of the following circumstances:

Very large number of files are deployed.

Deployments are scheduled often.

The administration servers subscribing to the reporting events are running and thus are unable to receive the events.

If you experience performance problems related to your event reporting, it is highly recommended that you use a commercial third-party database for the reporting message store-and-forward system by each OpenDeploy server with reporting enabled.

Each OpenDeploy server instance requires its own database /instance/partition of a database server.

To configure the store-and-forward database to a commercial database, follow these steps:

1. Stop the OpenDeploy server and administration server.

2. Open the jmsConfig.xml file using your favorite text or XML editor. This file resides in the following location:

od-home/etc

Configure the RdbmsDatabaseConfiguration element for use with your new database, including the new JDBC driver, URL, user, password, and any other attributes required to connect to your database.

Save and close the file.

3. Open the eventReportingConfig.xml file. This file resides in the following location:

od-home/etc

Add the path to your JDBC drivers to the environment name="OPENJMS_CP" element.

Save and close the file.

4. Add the path to your JDBC driver(s) to your host’s CP environment variable.

5. Run the following command from the prompt:

od-home/lib/dbtool create config od-home/etc/jmsConfig

to create the necessary tables in the database.

After running the command, the following message should appear:

Successfully created tables.

295

Reporting

Otherwise, you will probably receive an error message from your JDBC driver or database about why it could not connect to the database. If this happens, you will need to correct the problems in one or more of the following areas:

The JDBC settings in the jmsConfig.xml file.

The classpath information in the dbtool script (and correspondingly in the eventReporting.xml file).

The database system itself.

Under rare circumstances you might see “post-connection” errors about why it could not create certain tables. If these cases, you must the tables manually. Run the following command to drop any tables that may have been created:

od-home/lib/dbtool drop config od-home/etc/jmsConfig

Next, find the script appropriate for you database from the following location:

od-home/openjms/config/db

and execute it with your database script execution tool.

You can test that OpenDeploy is working with the new database by restarting the OpenDeploy server and checking some of the logs for error messages. Look for any error messages that appear to have originated from OpenJMS. These indicate that the store-and-forward mechanism did not start properly. The error messages contained in the log will help in determining the exact reason.


Custom Reports

Custom Reports

Custom reports are reports that provide information on deployments. These reports are accessed through the browser-based user interface. You can also download them to your local host, and open them using other applications.

Custom reports have a fixed structure that provides the basic information that typical OpenDeploy users want without having to build a complete reporting structure yourself. However, you can apply a variety of search criteria to this structure to refine the report to the deployment information and timeframe you want.

When generated, a custom report contains the following specific type of reports:

Deployment report — displays information regarding the overall deployment.

Deployment leg report — displays information regarding the deployment of files from a source to a specific target, either as a single target deployment, a fan-out deployment, or a multi-tiered deployment.

Manifest report — displays information on the status of each item deployed in a specific leg of the deployment.

You can access a particular deployment leg report from within the deployment report, and a particular manifest report from the deployment leg report.

297

Reporting

Configuring Custom Report Queries

Custom reports are generated based on the user-defined custom report query. This query determines the search criteria used to determine the contents of the report.Custom report queries are created in the Custom Report window (Figure 1).

Figure 1: Custom Report Window

The Custom Report window contains a variety of items with which you can create a custom report query including the following search criteria:

Deployment name.

User name of the individual starting the deployment.

Whether the search should include only deployments that are completed, in-progress, or failed, or whether it should include all deployments.

Whether the report should cover OpenDeploy servers sending or receiving deployments.

Source and targets (if applicable) of the deployment.

Start and end timeframe covered by the report


Custom Reports

Creating Custom Report Queries

To create a custom report query, following these steps:

1. Select Reports > Custom Report to display the Custom Report window.

2. Enter the name of the deployment in the Name box if you want to limit the report’s coverage. If you leave the Name box empty, all applicable deployments are included in the report.

3. Enter the appropriate user name in the Owner box if you want to limit the report to those deployments started by that individual. If you leave the Owner box empty, all applicable deployments started by any user are included in the report.

4. Select one of the following status types for the deployments from the Status list:Completed

In-progress

Failed

You can also select All to include all three status types in the report.

5. Select one of the following options from the View list:

Sending — includes information from servers sending deployments.

Receiving — includes information from servers receiving deployments. If you select Receiving, the Target Host list appears in the window (Figure 2).

Figure 2: Target Host List When Receiving Is Selected

6. Select the button associated with the following timeframe option you want to apply to the custom report, and complete the information required for that option:

In the Last — enter a number and select the corresponding measure of time (hour, day, week, month) that the report will cover.

From/To — enter the hours and minutes and select the dates from start to end that will be covered by the report. You can select the Calendar buttons to display a calendar tool to select the days.

You can click Reset at any time while creating a custom report to delete the values you entered and start again.

After you have completed creating the custom report query, you can generate the report. You can also save the custom report query as a quick report if you want to run the report in the future without having to recreate it. See “Generating Custom Reports” on page 300 and “Saving Custom Reports as a Quick Reports” on page 305 for more information.

299

Reporting

Exporting Custom Report Queries

After you create your custom report query, you can export it into the SQL Query Report window, where you can further customize it. SQL query reports provide a greater level of flexibility to reporting than is available with custom reports.

To apply a custom report to an SQL query, click SQL Report in the Custom Report window to display the SQL Query Report window. The query information from the custom report is automatically imported into the SQL query displayed in the SQL Query Report window. See “SQL Query Reports” on page 310 for more information.

Generating Custom Reports

You can generate a custom report after you have configured it by clicking Generate Report in the Custom Report window. The Deployment Report window is displayed (Figure 3), containing the generated report.

Figure 3: Deployment Report Window

Preconfigured Reports

OpenDeploy includes the following preconfigured reports, known as quick reports, that are available for generation at any time:

Deployments in the past 24 hours

Sender completed deployments in past 24 hours

Sender failed deployment in past 24 hours

You can also save any custom report query you create as a quick report and generate it at a later time. See “Saving Custom Reports as a Quick Reports” on page 305 for more information.


Custom Reports

Deployment Report Structure

Deployment reports (Figure 4) provide general information on the overall deployment. These are the reports initially displayed when you select a custom report.

Figure 4: Deployment Report

Deployment reports are displayed in table format. Each column represents a category of information in the report:

Name column — displays the name and instance (if appropriate) of the deployment. This name is a link, which when clicked, displays an additional report on each leg of the selected deployment.

ID column — displays a unique ID for the deployment.

Owner column — displays the user name of the user who ran the deployment.

Source Host column — displays the name or IP address of the source host. If a particular instance of the OpenDeploy server is being used, that instance name is also included.

Route ID column — displays a route ID used in routed deployments.

Start column — displays the start time of the deployment, using the following format:

YYYY-MM-DD hh:mm:ss

End column — displays the end time of the deployment, using the following format:

YYYY-MM-DD hh:mm:ss

Status column — indicates whether the deployment has completed, failed, or has been skipped.

Trigger column — displays how the deployment was started, such as manually, or by schedule.

Options column — displays information about the deployment type and features.

Status Details column — displays additional information as appropriate.

301

Reporting

Deployment Leg Report

Deployment leg reports (Figure 5) provide information on each leg of a specific deployment.

Figure 5: Deployment Leg Report

Each deployment leg can represent a deployment of content from a source to a target, as in the case of a single target or fan-out deployment, or it can represent the deployment of content from one tier to another tier in a multi-tier deployment.

You can display the deployment leg report for a specific deployment by clicking that deployment’s link under the Name column in the deployment report table. Deployment leg reports contain the following information:

Leg Label (Next Deployment) column — displays the deployment leg name, which is a combination of the target node name and the deployment definition name, as a link. When clicked, the Manifest Report for that leg is displayed.

Source column — displays the source of the deployment leg. If a particular instance of the OpenDeploy server is being used, that instance name is also included.

Target column — displays the target of the deployment leg.

Start column — displays the start time of the deployment leg, using the following format:

yyyy-mm-dd hh:mm:ss

End column — displays the end time of the deployment leg, using the following format:

yyyy-mm-dd hh:mm:ss

Encryption column — displays the type of encryption used, if any.

Status column — displays whether the deployment leg was completed or failed.

Detail column — displays any other information regarding the deployment


Custom Reports

View Details button — click to display the Leg Report Details window (Figure 6), which contains information on the deployment leg, including the leg name, source and target platforms, and source and target file locations.

Figure 6: Leg Report Details Window

Manifest Report

Deployment manifest reports (Figure 7) provide information on the content associated with a specific deployment leg.

Figure 7: Deployment Manifest Report

Click the link in the deployment’s Leg Label (Next Deployment) column entry to display the manifest report for that leg.

303

Reporting

The report provides the information on each file and directory deployed:

Update Source column — displays the name of the status file associated with the deployment. The file resides in the following location:

od-home/(od-instance)/tmp

Update Action column — displays whether the deployed item was new, updated, or deleted.

Type column — displays whether the deployed item was a file, a directory, or a link.

Reason column — displays the reason the item was acted upon.

Status column — displays whether the deployed item was completed, failed, or skipped.

Status Detail column — displays additional information as appropriate.

Downloading Custom Reports

You can download a generated custom report to your local host or another computer on the network. The saved file is a comma-delimited file (CSV) that can be viewed and used by another application, such as a database or a text editor. Figure 8 shows a custom report being displayed in Microsoft Excel.

Figure 8: Generated Custom Report Opened in Microsoft Excel

Downloading a generated custom report allows you to modify the report, copy and paste portions into other documents, or use the application to save it under a different format.

To download a generated custom, follow these steps:

1. Click Download Report in the Deployment Report window. A message window appears prompting whether you want to open or save the report file.

2. Click Save. You are prompted to locate where you want to save the file and under what file name.

3. Navigate to the location where you want the file to be saved, and provide a file name.

4. Save the file.


DAS Custom Reports

Saving Custom Reports as a Quick Reports

You can save any custom report query as a quick report, where you can access and generate the report at anytime. Click Save Quick Report when you create your custom report query. You will be prompted to name the report query. That named report is subsequently listed among the quick reports in the Deployment Reports window. See “Quick Reports” on page 313 for more information.

DAS Custom Reports

Database auto-synchronization (DAS) custom reports are similar to regular custom reports already described in this chapter in that you can enter details and run or save a report query. DAS custom reports provide information about database updates resulting from TeamSite event triggers.

Refer to Chapter 4, “Database Auto-Synchronization” on page 81 in the Database Deployment for OpenDeploy Administration Guide for more information on the DAS feature.

You can configure DAS custom reports in the DAS Custom Report window (Figure 9).

Figure 9: DAS Custom Report Window

Any unique DAS custom report configuration you make in this window can be saved as a quick report that you can generate at a later date.

305

Reporting

To generate DAS custom reports, follow these steps:

1. Select to Reports > DAS Custom Reports to display the DAS Custom Report window.

2. Select the timestamp format you want from the Timestamp Format list.

The formats use the following syntax:

yy or yyyy indicates the two- or four-digit year (“2004” or “04”), respectively.

MM indicates the two-digit month (for example, January would be “01”;

dd indicates the two-digit day (“01”–“31”).

mm indicates the two-digit minute value (“00”–“59”).

ss indicates the two-digit second value (“00”–“59”).

3. Enter the period from which the report starts using the specified timestamp format in the From box.

4. Enter the period to which the report ends using the specified timestamp format in the To box.

5. Select the matching criterion for the period of time covered by the From and To values from the Timestamp list.

6. Select the OpenDeploy server on which DAS is running from the Selected Server list.

7. Select the matching criterion for accessing the file that DAS deployed from the Filename list, and enter all or some of the file name in the associated box.

8. Select the matching criterion for the TeamSite area where the file resides from the Area (vpath of workarea) list, and enter all or some of the area in the associated box.

9. Select the matching criterion for the deployment configuration file from the Config File list, and enter all or some of the configuration file in the associated box.

10. Select one of the preconfigured DAS deployment names from the Deployment Name list.

11. Select the result (successful or failed) on which the report is based from the Deploy-ment Result list.

12. Select one of the preconfigured actions from the Action list.

13. (optional) Click Save Quick Report if you want to keep this DAS custom report con-figuration for future report generation.

14. Click Generate Report.

You can click Reset at any time to restore the values in the DAS Custom Report window to their default settings, and start over.


ControlHub Custom Reports


ControlHub custom reports allow you to generate reports on a variety of ControlHub activities, such as content submissions and published editions over a specified period of time. ControlHub custom reports are available only when you use OpenDeploy in conjunction with ControlHub.

Note: If ControlHub is not installed and running on your OpenDeploy host, then the ControlHub Custom Report link does not appear under Reports in the OpenDeploy user interface.

Refer to Chapter 14, “Configuring Reporting” on page 243 in the ControlHub Administration Guide for information on configuring ControlHub reporting.

You can configure ControlHub custom reports in the ControlHub Custom Report window (Figure 10).

Figure 10: ControlHub Custom Report Window

307

Reporting

You can determine the scope of the report by selecting a data range. Depending on which report type you select, additional options appear under Report Properties that allow you to further limit the report. The following table lists the report types, their descriptions, and a listing of those filtering options associated with each one.

Any unique ControlHub custom report configuration you make in this window can be saved as a quick report that you can generate at a later date.

To generate ControlHub custom reports, follow these steps:

1. Select to Reports > ControlHub Custom Report to display the ControlHub Custom Report window.

2. Select one of the types of reports that you want to generate from the Report Type list (see table above).

3. (optional) Enter values in any of the items that appear under Report Properties when you select the report type (see table above).

4. Select the button associated with the following timeframe option you want to apply to the custom report, and complete the information required for that option:

In the Last — enter a number and select the corresponding measure of time (hour, day, week, month) that the report will cover.

From/To — enter the hours and minutes and select the dates from start to end that will be covered by the report. You can select the Calendar buttons to display a calendar tool to select the days.

Report Type Description Associated Properties

Completed Jobs Displays all workflows which have completed within the given time.

Workflow

Published Editions Displays all editions published within the given time period.

StoreBranch

Content Submission Displays all submits that occurred within the given time period.

BranchAreaUser ID

Files Owned by Active Task

Displays all the active tasks with the files associated with them.

Branch

New Active Jobs Displays all the active (not completed) jobs in the given date range.

WorkflowTask Area VPath (from where the workflow job was started)



5. (optional) Click Save Quick Report if you want to keep this ControlHub custom report configuration for future report generation.

6. Click Generate Report.

You can click Reset at any time to restore the values in the ControlHub Custom Report window to their default settings, and start over.

The generated ControlHub custom report is displayed in the Deployment Report window (Figure 11). This example shows a generated report.

Figure 11: Generated ControlHub Custom Report

309

Reporting

SQL Query Reports

SQL query reports allow you to design and compose your own reporting query when the custom report feature does not offer enough flexibility. Using SQL, you can compose a single search query that can include individual columns from a variety of available tables to create a completely customized report. SQL query reports can be saved as quick reports for future usage, the same as with custom reports.

SQL query reports are created in the SQL Query Report window (Figure 12).

Figure 12: SQL Query Reports Window

The SQL Query Report window is displayed when you select Reports > SQL Query Report in the browser-based user interface. This window is also displayed when you click the SQL Report button in the Custom Report window, allowing you to import your custom report into the SQL Report window. Here, you can further customize it by adding user-defined tables, columns, and search terms.


SQL Query Reports

SQL Report Queries

The SQL Query Report window contains the information required for you to create your SQL report query (Figure 13).

Figure 13: Composing SQL Query Scripts

The Valid Table Name list contains those tables whose individual columns are valid and available for inclusion in an SQL search query. The Valid Column Name list contains those columns associated with the table selected in the Valid Table Name list. The Select and Copy list contains query terms associated with the Valid Column Name selection.

Both of these lists are for information purposes only. You can use the valid table and column information provided in these lists in your SQL query script.

You can create a single SELECT query in the SELECT box. In this box you can enter those valid table and column names, along with the appropriate search conditions. You can copy and paste selected items listed in the Select and Copy list into the SELECT box, or use drag-and-drop to build your query.

Creating SQL search queries requires some level of SQL expertise. If you are not comfortable with composing SQL scripts, you should use the custom reports feature instead. See “Custom Reports” on page 297 for more information.

Access to Reporting Server Database Tables

The OpenDeploy reporting server uses unqualified SQL. Therefore, the user specified in the reporting management configuration file (adminEventReportingConfig.xml) for accessing the database must also be the owner of the tables. See “Specifying the Database User Name and Password” on page 286 for more information on configuring the user.

Refer to Chapter 20, “Reporting Server Database Schema” on page 317 in the OpenDeploy Reference for a list of available tables you can use with this feature.

Case Sensitivity

Case sensitivity in SQL query statements is handled differently for various platforms and RDBMS vendors. You should be aware of that when writing your own custom queries. Refer to your database documentation for more information.

311

Reporting

Creating SQL Queries

To create an SQL query, follow these steps:

1. Select Reports > SQL Query Report to display the SQL Query Report window.

2. Review those available tables in the Valid Table Names list.

3. Review those available columns that correspond to a particular table by selecting the table from the table list. The corresponding columns are displayed in the Valid Column Names list.

4. Compose a single search SQL query by entering the valid tables, columns, and search conditions in the SELECT text box.

You can compose your query by copying and pasting a selected table or column name into the SELECT text box, or by using drag-and drop.

You can click Reset at any time while creating an SQL query report to delete the values you entered and start again.

After you have completed creating the SQL report query, you can generate the report. You can also save the SQL query report as a quick report if you want to run the report in the future without having to recreate it.

Generating SQL Query Reports

You can generate an SQL query report after you have created the report query by clicking Generate Report in the SQL Query Report window. The Deployment Reports window is displayed containing the generated report (Figure 14).

Figure 14: Generated SQL Query Report

Downloading an SQL Query Report

You can download a generated SQL query report to your local host or another computer on the network. The saved file is a comma-delimited file that can be viewed and used by another application, such as a database or a text editor. The procedure is the same as for custom reports. See “Downloading Custom Reports” on page 304 for more information.


Quick Reports

Saving an SQL Query Report as a Quick Report

You can save any SQL query report as a quick report, where you can access and generate the report at anytime. Click Save Quick Report when you create your SQL query report. You will be prompted to name the report. That named report is subsequently listed among the quick reports in the Deployment Reports window. The following section describes quick reports.

Quick Reports

You can save any custom, ControlHub, or SQL query report you create as a quick report. The report query is saved and can be accessed and run at any time with no additional report configuration required. If you plan to run certain reports on a regular basis, you should consider saving them as quick reports.

Quick reports are displayed in the Deployment Report window (Figure 15).

Figure 15: Deployment Report Window

The Quick Report list contains all those quick reports that you can access and display. The following preconfigured quick reports are also included for your use with no additional configuration required:

Sender failed deployment in past 24 hours — displays a report of failed deployments over the previous 24 hour period.

Deployments in the past 24 hours — displays a report of all deployments over the previous 24 hour period.

Sender completed deployments in past 24 hours — displays a report of all completed deployments over the previous 24 hour period.

Selecting an entry from the Quick Report list runs that report and displays the results in the Deployment Report window. You can also download the report to your local host by clicking Download Report. See the sections on custom, ControlHub, and SQL query reports for instructions on how to use this feature for those types of reports.

313

Reporting

Adding New Entries to Quick Report List

You can add any custom, ControlHub, or SQL query report you create to the Quick Report list by clicking the Save Quick Report button in the respective Custom Report, ControlHub Custom Report, or SQL Query Report window at the time of creation.

Editing Existing Entries

You can edit a custom, ControlHub, or SQL query listed in the Quick Report list through the Edit Quick Report window (Figure 16).

Figure 16: Edit Quick Report Window

Select Reports > Edit Quick Report to display the Edit Quick Report window.

The Edit Quick Report window lists all available quick reports, along with buttons to edit or delete the quick report you select. Selecting a quick report entry from the Quick Report list and clicking Edit Query will display the associated Custom Report, ControlHub Custom Report, or SQL Query Report window, where you can modify the report. After making you changes, you can save the report under its existing name, or save it with a new name. You can also generate the report.

Deleting Entries

You can delete any existing quick report by opening the Edit Quick Report window, selecting the quick report you want to delete from the Quick Report list, and clicking Delete. After deleting a quick report, that report no longer appears in the Quick Report list, and is no longer available for use.


Managing Report Data

Managing Report Data

OpenDeploy includes a report maintenance feature to help administrators manage the amount of event reporting data that is maintained in the reporting database. The Report Maintenance window (Figure 17) includes controls that allow you to delete sender, receiver, DAS, or ControlHub report data based on a time period prior to the current time, or prior to a specified date. After reporting data is deleted, you cannot recover it.

Figure 17: Report Maintenance Window

The window also includes buttons you can click to access the different types of reporting windows, such as custom or SQL reports.

To delete reports older than a specified time, follow these steps:

1. Select Reports > Report Maintenance to display the Report Maintenance window.

2. Select the type of reporting data (sender, receiver, DAS, or ControlHub) from the Remove list.

3. Select one of the Older Than options and enter the associated time and date informa-tion:

Older than the specified time period before the current date. Enter the number and type of time measurement (hours, days, weeks, months). Report data older than the specified amount of time from now will be deleted.

Older than the specified time period before a specified date. Enter the time (hour and minute) and the date (day, month, year). Report data that is older than this specified time and date will be deleted.

Click Reset if you want to clear your specified values and start again.

4. Click Remove Reports to remove the reporting data.

315

Reporting

Reporting Database Sizing Guidelines

This section provides guidelines on the size of the reporting database for the following uses of OpenDeploy:

Sending

Receiving

Database auto-synchronization (DAS)

The total reporting database size in bytes is the sum of these three databases.

Sending OpenDeploy Server

Combine the following values:

((Number of deployments) * 350) +

((Number of deployments) * (average number of legs per deployment) * 600) +

((Number of deployments) * (average number of legs per deploymen)t * (average percent of deployments that are file deployments) * (average number of files per leg) * 350) +

((Number of deployments) * (average number of legs per deployment) * (1 – average percentage of deployments that are file deployments) * average number of database records per deployment leg) * 750)

If you are not doing any database deployments, then the average would be zero. Use zero for that part of the formula.

Receiving OpenDeploy Server

Combine the following values:

((Number of deployments) * 700) +

((Number of deployments) * (average percentage of deployments that are file deployments) * (average number of files per deployment) * 500) +

((Number of deployments) * (1 – average percentage of deployments that are file deployments) * (average number of database records per deployment) * 950)

If you are not doing any database deployments, then the average would be zero. Use zero for that part of the formula.

Database Auto-Synchronization (DAS)

(Number of DAS events) * 882


Chapter 9

Encryption

OpenDeploy provides two methods of encryption:

Weak (40-bit) symmetric key file-based encryption

Secure data transfer using Secure Sockets Layer-based (SSL) encryption

These types of encryption are mutually exclusive and cannot be used in conjunction with one another. Be sure not to include attributes for both types of encryption in the same configuration.

Encryption can be specified both at the OpenDeploy base server and receiver level, and at the individual deployment configuration level. Encryption settings specified in the deployment configuration level will automatically override any encryptions settings in the server configuration.

Encryption is not supported by the EasyDeploy base server software. To use encryption, you must upgrade to the full-feature base server software.

Symmetric Key Encryption

OpenDeploy provides 40-bit encryption support for content transfers through referencing an encryption algorithm key file specified in the base server or receiver configuration file. OpenDeploy symmetric key deployment provides basic encryption support with minimal performance impact on content deployment. However, symmetric 40-bit encryption is breakable by brute force attack with a modest amount of computing power and is potentially vulnerable to unauthorized users with the same symmetric key who can intercept data in transit.

Configuring OpenDeploy for Symmetric Encryption

Symmetric key encryption requires that the key file’s path be specified in the keyFile attribute of the localNode element in both the deployment configuration, and in the server configuration file of the receiving base server (by default odbase.xml) or receiver (by default odrcvr.xml). The base server configuration file of the sending server is not affected. The keyFile attribute specifies the absolute path to the symmetric key. Here is an example of the OpenDeploy server mars being configured for symmetric key encryption:

<localNode host="mars" keyFile="/local/OpenDeploy/conf/keyfile.txt"/>

317

Encryption

Using Symmetric Encryption with Reverse Deployments

If you are performing a reverse deployment using symmetric key encryption, you must include the path to the symmetric key file residing on the reverse source (normally the receiving server in a forward deployment) in the deployment configuration. This is the same location as specified in the base server or receiver configuration file of the reverse source. This differs from a forward deployment, where the configuration would include the path to the key file where it resides on the source. The deployment configuration must include the path syntax of the reverse source. The path to the symmetric key file is defined in the keyFile attribute of the localNode element.

In the following example, the source mars has the base server software installed and is running on UNIX. The target venus has the receiver software installed and is running on Windows. In a typical forward deployment using symmetric key encryption, the localNode element in the deployment configuration residing on mars would be:


and the localNode element in venus’ receiver configuration file would be:

<localNode host="venus" keyFile="C:\encryption\keyfile.txt"/>

In a reverse deployment involving these two servers, the localNode element in the reverse deployment configuration would be:

<localNode host="mars" keyFile="C:\encryption\keyfile.txt"/>

and the localNode element in the base server configuration file on mars would be:



Secure Data Transfer with SSL


OpenDeploy uses X509.v3 digital certificates and Secure Socket Layer (SSL) v3 for secure content transfer. OpenDeploy comes packaged with its own certificate authority, which should be used for certificate generation. A packaged script aids in the creation of the certificate authority and subsequent certificate generation.

This release of OpenDeploy supports DSA and RSA certificates, but has only been tested using the certificate authority that comes packaged with OpenDeploy.

Certificates that require a password to be used will not work with OpenDeploy.

The use of 168-bit encryption is available within the United States of America and most other countries. You can also set up OpenDeploy to accept multiple levels of encryption.

The following sections describe the process of creating digital certificates. This is a multi-step process that requires familiarizing yourself with the complete process before beginning any individual tasks. You should read this documentation completely before actually attempting this process.

Obtaining Additional SSL Information

You can find additional information on the SSL through the following Web site:

www.openssl.org

For more information about encryption and ciphers, consult a cryptography reference manual such as Applied Cryptography (Bruce Schneier, ISBN 0-471-11709-9).

Setting Up for SSL Private Keys and Certificates

Each peer server running OpenDeploy contains an SSL configuration within the base server or receiver configuration file’s localNode element. OpenDeploy uses the OpenSSL implementation of the SSL. Setting up OpenDeploy involves the following tasks:

Editing the certificate authority configuration file.

Setting up the certificate authority (CA).

Generating the certificates and keys for the base server.

Generating the certificates and keys for the receiving nodes.

Copying the certificate/key pair and the CA certificate to the other OpenDeploy nodes.

Configuring the OpenDeploy base server configuration file (by default odbase.xml) if the base server is to receive deployment using SSL.

Configuring the receiver configuration file (by default odrcvr.xml) for SSL data transfer encryption.

Configuring the deployment configuration for SSL data transfer encryption.

319

Encryption

If you have one OpenDeploy sender and one OpenDeploy receiver, these tasks create two unique public and private key pairs that are signed by the same certificate authority. One key pair is copied to the source. The other key pair and the CA’s certificates are copied to the target. These tasks are required regardless of what level of encryption you want to use. Either the source or target has the ability to request a verification of the certificate authority before the deployment can occur. See “Configuring OpenDeploy for SSL Data Transfer Encryption” on page 329 for more information.

The certificate authority consists of a set of programs used to generate public and private key pairs and a database that contains state information. The programs are installed in the following location:

od-home/bin

The following table lists those files used for generating the certificate authority:

The openssl.exe and openssl programs are command line tools for using the various cryptography functions of OpenSSL's cryptography library from the shell. See “Obtaining Additional SSL Information” on page 319 for more information.

The openssl.cnf file is the configuration file for running the openssl utility.

The CA.bat and CA.sh files are the wrapper scripts that are used both to create the certificate authority and to generate the certificates and private keys for OpenDeploy.

By default, the database is contained in the directory where the programs are run. If future public and private key pairs are created using a different certificate authority, OpenDeploy will not be able to deploy to or from a server with keys created by the original certificate authority. If a problem occurs during key generation, it is best to delete the created key and authority and start over.

Much of the state information that is used in creating the certificate/key pairs, including the certificate authority’s certificate, is maintained in this directory. If future public and private key pairs are created using a different certificate authority, or the current authority is overwritten, OpenDeploy will not be able to deploy files using these certificates.

Windows UNIX

openssl.exe openssl

openssl.cnf openssl.cnf

CA.bat CA.sh



Setting Up the Certificate Authority

To set up the OpenSSL certificate authority, follow these steps:

1. Verify that the od-home/bin directory is included in the PATH environment variable.

UNIX — enter env|grep PATH at the prompt.

Windows — right click on the My Computer icon and select Properties from the pop-up menu to open the System Properties window. Next, select the Advanced tab to make it active. Finally, click Environment Variables. to open the Environmental Variables window. The current path in use is displayed in the System variables list.


od-home/bin

3. Make a backup copy of openssl.cnf file, for example openssl.cnf_orig.

4. Open the openssl.cnf file using your favorite text editor.

5. Change the following line if you would like the certificate to last for longer than a year.

default_days =365 # how long to certify for

6. Change the default values for your own installation. These are located in the [ req_distinguished_name ] section of the file.

7. Ensure that the RANDFILE variable in openssl.cnf is set to:

RANDFILE=.rnd

When invoking the OpenSSL utilities, run them in od-home/bin, which is where the openssl.cnf file also resides.


9. Create a seed file (*.rnd) for the random number generator by performing the follow-ing steps:

a. Enter the following command at the prompt:

netstat -a > .rnd

b. Move this .rnd file to the following location:

od-home/bin

As an alternative, you can copy any file sufficiently large into a .rnd file to make it a seed file. Log files are good example of random data for seeding. The key requirement is that the data used for seeding is truly random or very difficult to reproduce.

OpenSSL uses a pseudo random number generator (PRNG) to generate public and private key pairs. The PRNG needs to be seeded with a satisfactory amount of genuine random data so it does not generate predictable keys.

“Obtaining Additional SSL Information” on page 319 for more information on seeding methods.

321

Encryption

10. Create the new certificate authority by entering the following command (depending on the platform) at the prompt:

Windows — CA.bat -newca or

UNIX — CA.sh -newca (press Enter at the prompt to create the new certificate authority.)

By default, the certificate authority will have a life span of 365 days before expiring. If you want to specify another expiration date, you can append the command with the -days option and specify the number of days until expiration. See “Certificate Authority Expiration” on page 323 for more information.

If the certificate authority already exists, the script will print harmless error messages regarding existing directories, and finish execution.

Creating the certificate authority results in the following directory being created:

od-home/bin/demoCA

and copies the authority's certificate/key pair into it. A certificate authority can be initialized from a previously existing CA certificate, or it can be created as a completely new authority. The default method is to create a new authority.

11. Enter the appropriate information in response to the following prompt:

You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank. For some fields there will be a default value,

If you enter '.', the field will be left blank.-----Country Name (2 letter code) [US]:State or Province Name (full name) [California]:Locality Name (eg, city) [Sunnyvale]:Organization Name (eg, company) []:InterwovenOrganizational Unit Name (eg, section) []:EngineeringCommon Name (eg, YOUR name) []:Engineering Certificate AuthorityEmail Address []:

The prompts for country, state or province, and locality contain default values that you can accept, or you can enter your own information. The prompts for organization name, organizational unit name, common name, and email address are optional. You can either enter a value, or leave them blank by entering the value “.”. All of the inputs to the prompts constitute the Distinguished Name.

The more unique values you provide for these optional prompts, the more effective the certificate authority will be. Each certificate authority you create must be unique from all other certificates. One method to ensure disparate Distinguished Names is by providing dissimilar values for the Common Name prompt.



You can begin the certificate authority process by deleting the directory containing the certificates. There is no penalty for this until you begin issuing certificates. You will not be able to use certificates that have the same Distinguished Name as the certificate authority.You will invalidate all certificates signed by a particular certificate authority by deleting its default directory.

Certificate Authority Expiration

By default, any certificate authority you create has a life span of 365 days before it expires. However, you can specify another expiration period at the time of creation if you want by appending the CA.bat newca or CA.sh newca command with the -days option and a number representing the number of days the certificate authority is valid before expiring.

For example, if you wanted to specify a certificate authority expiration date of 200 days after creation, you would enter one of the following commands at the prompt:

Windows — CA.bat -newca -days 200 or

UNIX — CA.sh -newca -days 200

The expiration date of the generated certificate is specified in the openssl.cnf file. If the expiration date of the certificate does not match the certificate authority you specified using the -days option, OpenDeploy will assign the shorter expiration date of to certificates generated from the authority. See “Certificate Expiration” on page 325 for more information.

Generating a Certificate

Creating a certificate is very similar to creating the certificate authority and includes many of the same prompts for information. When generating a certificate, the authority is assumed to exist already. If you have one OpenDeploy sender and one OpenDeploy receiver, you must generate two certificates, one for the source and one for the target. You can also generate one certificate set and rename this set to be source and target keys. You must have a certificate/key pair for every OpenDeploy server you want to be included in SSL deployments.

To generate a certificate for an OpenDeploy server, follow these steps:

1. Navigate to the od-home/bin directory.

2. Generate a new certificate and key by entering the following command (depending on the platform) at the prompt:

Windows — CA.bat -certall or

UNIX — CA.sh -certall

The certificate wrapper script generates RSA certificates only. To generate DSA certificates, do not use the CA scripts. Consult the OpenSSL Web site for more information.

323

Encryption

3. Enter the appropriate information in response to the following prompt:

You are about to be asked to enter information that will beincorporated into your certificate request.What you are about to enter is what is called a Distinguished Name or a DN.There are quite a few fields but you can leave some blank.For some fields there will be a default value, If you enter '.', thefield will be left blank.-----Country Name (2 letter code) [US]:State or Province Name (full name) [California]:Locality Name (eg, city) [Sunnyvale]:Organization Name (eg, company) []:InterwovenOrganizational Unit Name (eg, section) []:EngineeringCommon Name (eg, YOUR name) []:Receiver certificateEmail Address []:

You cannot have two or more certificates with the exact same information. Each certificate must be unique. The difference between the certificate and the certificate authority can be identified by the different Common Name values. This value can be a reminder of the use to which you expect to put the certificate, for example, a receiver.

4. Answer yes at the prompts to sign and then commit the certificate:

Sign the certificate? [y/n]: y

1 out of 1 certificate requests certified, commit? [y/n]: y

At the conclusion of these steps a private key file called newreq.pem and a certificate file called newcert.pem are generated.

5. Copy the generated certificate and key to the appropriate locations. A recommended place to store certificates and keys is:

od-home/cert

You must create this directory manually, as it is not generated during the installation. You should also rename the certificate and key to reflect their roles in the deployment cycle because newly generated certificate/key pairs will overwrite the previously existing newreq.pem and newcert.pem files. For example, name your source key files odsrckey.pem and odsrccert.pem, and your target key files odtgtkey.pem and odtgtcert.pem.

6. Remotely copy the generated certificates, private keys, and the CA certificate to the appropriate location on each peer server, depending on which peer server the certifi-cate/key pair is intended. All OpenDeploy servers using SSL encryption must have these items regardless of what level of checking (request, required, or none) is con-figured.

Secure file transfer protocol (SFTP) and secure copy (SCP2) are good methods for moving these items to remote locations. For maximum security, you should physically transport them on a tape or diskette.Since you also have to move the certificates to the target, you might choose to compress and package these items together into a .tar or .zip file before you do the transfers to peer servers.



Certificate Expiration

The life span of the generated certificate is specified by the default_days attribute in the openssl.cnf file. This number is the expiration days for certificates newcert.pem generated based on cacert.pem. The default expiration period is 365 days.

If the expiration date of the certificate does not match the certificate authority you specified using the -days option, OpenDeploy assigns the shorter expiration date to certificates generated from the authority. In some cases, you might want to set the expiration date for certificate authority for a longer period and periodically expire the certificate using the same certificate authority.

Support for Third-Party Certificate Authority

You can use of a third-party certificate authority (CA) for SSL encryption as an alternative to the CA included with OpenDeploy. The procedure for using third-party CA differs depending on the type.

To use a third-party CA, follow these steps:

1. Generate a certificate signing request CSR/private key pair using the following command:

Windows — CA.bat -newreq or

UNIX — CA.sh -newreq

Using the -newreqþoption generates a CSR/private key pair (just like the -certall option) but does not sign the CSR with the local OpenDeploy CA, so no certificate is created. In contrast, the -certall command performs the certificate generation and then has the OpenDeploy CA sign the certificate.

The CSR and private key are both generated into the file newreq.pem.

2. Send the CSR to the third-party CA using one of the following methods:

If the CA can accept the CSR in PEM format (which is ASCII-based), open the newreq.pem file and copy the section bounded by "-----BEGIN CERTIFICATE REQUEST-----" and "-----END CERTIFICATE REQUEST-----" (including those lines). Use the third-party’s approved method to send them the CSR, such as in an email message, or through a Web form.

If the CA requires the CSR be submitted in DER format (which is binary-based), you must convert the newreq.pem file to DER format by running the following command at the prompt:openssl req -config openssl.cnf -in newreq.pem -inform PEM -out

newreq.der -outform DER

Attach the converted newreq.der file to an email and send it to the third-party CA.

Upon receiving the CSR, the third-party CA will subsequently return the signed certificate and the CA’s own certificate.

325

Encryption

3. Get the new certificate and the CA certificate from the third party CA:

If the returned certificates are in PEM format, you can use them as-is by copying and pasting them into the files newcert.pem and cacert.pem.

If the returned certificates are in DER format, you must convert them to PEM format by running the following command at the prompt:openssl x509 -in CA_file.der -inform DER -out CA_file.pem

-outform PEM

where CA_file represents the names of the new certificate or CA certificate file as appropriate.

4. Update the localNode element in base server, receiver, and deployment configuration files as necessary to reference to your signed certificate, your private key, and the third-party CA's certificate. For example:

<localNodehost="mars"sslCertificate="path_to_third-party_signed_certificate"

sslPrivateKey="path_to_local_generated_key (ex. newreq.pem from step 1)"sslCaCertificate="path_to_third-party_CA_certificate"...>

Changing OpenSSL Defaults

Much of the process for generating certificates has been automated, and much of the inputs to the automation can be defaulted. These defaults are specified in the following configuration file:

od-home/bin/openssl.cnf

For example, should you need to relocate the .rnd file, you can modify the RANDFILE parameter in openssl.cnf to point to a different location before creating the certificate authority. OpenDeploy includes a configuration file for creating simple certificates. See “Obtaining Additional SSL Information” on page 319 for more information on modifying openssl.cnf.

SSL Configuration and Deployment Errors

Errors can occur when creating certificates or in setting up the deployments. Here are two of the most commonly reported error messages:

PRNG not seeded and

Unable to write 'random state'

These indicate that you have not seeded the random number generator with enough data. See “Setting Up the Certificate Authority” on page 321 for more information regarding seeding the random number generator.



If the following error message is displayed:

Self-signed certificate

this indicates that both the certificate and the certificate authority have the same name. You will discover this error when you try to use the two certificates together. Although you cannot generate two certificates with the same Distinguished Name, there is nothing to prevent you from generating the certificate authority and a certificate with the same name. The Distinguished Names of the two certificates must differ in at least one entry while creating the certificates.

You can look at the certificate generated from running the script with the -certall option, and observe the Distinguished Name of the issuing certificate authority. You can then regenerate the certificate and ensure that you are not reusing all of the certificate authority's name.See “Obtaining Additional SSL Information” on page 319 for more information regarding errors.

Verifying Certificates

You can verify the validity of the certificates you generate by entering the following command at the prompt:

Windows — CA.bat -verify or

UNIX — CA.sh -verify

If you have changed the name of the certificates since they were created, you must also add the certificate name to the command, for example:

CA.bat –verify odsrccert.pem or

CA.sh –verify odtgtcert.pem

If the certificate is valid, the following message is displayed:

certificate_name.pem: OK

For example, if you entered the following:

CA.bat -verify newcert.pem

the following message is displayed:

newcert.pem: OK

327

Encryption

However, if there is a problem, OpenDeploy will display an error message such as the following:

newcert.pem:/C=US/ST=California/L=Sunnyvale/O=Interwoven/OU=Engineering/CN=Engineering Certificate Authority error 18 at 0 depth lookup:self signed certificate/C=US/ST=California/L=Sunnyvale/O=Interwoven/OU=Engineering/CN=Engineering Certificate Authority error 7 at 0 depth lookup:certificate signature failure

An error message like this can be the result of not using a unique Common Name when generating certificates. See “Generating a Certificate” on page 323 for more information.

Using Multiple Certificates

In some cases, target OpenDeploy servers may receive deployments using SSL encryption from multiple OpenDeploy source servers. In these cases, you must configure the target server to work with multiple CA certificates. You can do this with any of the following methods:

Generate a new certificate with a unique CA for each sending base server, and add each one individually to the target server. This method provides you the most control over which senders will be accepted by the target.

You must update the localNode element’s sslCaCertificate attribute in the target’s server configuration file (by default odbase.xml or odrcvr.xml). The sslCaCertificate attribute value should be the path to a file that contains all the appropriate CA certificates concatenated together.

Use a single CA to generate a new certificate for each sending base server. This method requires less effort than the previous method because every target only has to have the one CA certificate to “trust” all the sending servers.

You must update the localNode element's sslCaCertificate attribute in the target's server configuration file (by default odbase.xml or odrcvr.xml). The sslCaCertificate attribute value should be the path to a file that contains the certificate of the CA used to create each of the base server certificates.

You can use both these methods to create a group structure among the sending servers. Each server could belong to one of several groups, and target servers could have the certificates of the CAs of the groups they wanted to allow connections from. For example, have one CA for servers in each geographical region of an enterprise. Target servers in a particular region could have in their CA list the CA from their own region, but target server corporate headquarters all of them.



Configuring OpenDeploy for SSL Data Transfer Encryption

After you generate and sign the certificates as described in the preceding sections, you must configure OpenDeploy to use SSL data transfer encryption. You can configure encryption using the following methods:

In the base server and receiver configuration files.

In the deployment configuration files.

Reverse deployments that are configured for SSL data transfer encryption require that both the reverse source and reverse target servers have SSL data transfer encryption configured in their base server or receiver configuration files as well, or the encryption will fail.

Encryption values are specified in the localNode element of the base server or receiver configuration files of the OpenDeploy server. If you specify SSL data transfer encryption in these configuration files, then all incoming deployments are expected to be encrypted this way.

Encryption values in the deployment configuration are also specified in the localNode element, and the same attributes apply. Encryption in the deployment files only apply to that deployment.

In both cases, you must have the following attributes and their values specified within the localNode element:

sslCertificate — enter the absolute path to the SSL public key certificate.

sslPrivateKey — enter the absolute path to the SSL private key certificate.

sslCaCertificate — enter the absolute path to the certificate authority. This allows OpenDeploy to authenticate the source from which the public and private key pairs for the source and targets are derived.

sslVerifyPeer — (optional) indicate which of the following conditions apply in regards to the verification that the certificate authority for each public and private key pairs comes from the same source. This source is the value specified in the sslCaCertificate attribute.

none — no verification is performed. This is the default value.

request — verification is performed if the certificate/key pair exists on the peer of the server making the authentication request before the deployment can occur.

require — verification must be performed, and the certificate/key pair must exist on the peer of the server making the request before the deployment can occur.

329

Encryption

Here is an example of how the localNode element and its encryption-related attributes might be configured for SSL data transfer encryption in the base server configuration file or in a deployment configuration:

<localNodehost="mars"sslCertificate="od-home/cert/odsrccert.pem"sslPrivateKey="od-home/cert/odsrckey.pem"sslCaCertificate="od-home/bin/demoCA/certs/cacert.pem"sslVerifyPeer="request"/>

Here is an example of how the localNode element and its encryption-related attributes might be configured for SSL data transfer encryption in the target receiver configuration file:

<localNodehost="venus"sslCertificate="od-home/cert/odtgtcert.pem"sslPrivateKey="od-home/cert/odtgtkey.pem"sslCaCertificate="od-home/bin/demoCA/certs/cacert.pem"sslVerifyPeer="request"/>

Ciphers

You can specify various ciphers to use in encryption. During a connection, the OpenDeploy source and targets will negotiate over which cipher to use. During the negotiation phase, OpenDeploy selects the highest priority cipher that both source and targets support. The use of ciphers is specified by the presence of the sslCiphers attribute in the localNode element, located in the base server or receiver configuration file. For example:

sslCiphers="cipherlist"

where cipherlist contains one or more ciphers, ranked left to right from highest priority to lowest priority, separated by colons (“:”). For example:

sslCiphers="EDH-RSA-DES-CBC3-SHA:DES-CBC-SHA"

The following is a list of all cipher strings and their meanings:

DH — cipher suites using DH, including anonymous DH.

ADH — anonymous DH cipher suites.

3DES — cipher suites using triple DES.

DES — cipher suites using DES (not triple DES).

RC4 — cipher suites using RC4.

RC2 — cipher suites using RC2.

IDEA — cipher suites using IDEA.

MD5 — cipher suites using MD5.

SHA1, SHA — cipher suites using SHA1.



Refer to the following Web site for more information on ciphers:

www.openssl.org/docs/apps/ciphers.html

OpenDeploy allows you to use the following types of ciphers:

No-authentication ciphers:

None

Low-strength (56 and 40 bit) ciphers:

EXP1024-RC4-SHA (56 bit)

EXP1024-DES-CBC-SHA (56 bit)

EXP1024-RC2-CBC-MD5 (56 bit)

EXP1024-RC4-MD5 (56 bit)

EDH-RSA-DES-CBC-SHA (56 bit)

DES-CBC-SHA (56 bit)

EXP-EDH-RSA-DES-CBC-SHA (40 bit)

Medium-strength (128 bit) ciphers:RC4-SHA

RC4-MD5 SSLversion 2 or version 3

High-strength (168 bit) ciphers:EDH-RSA-DES-CBC3-SHA

DES-CBC3-SHA

If sslCiphers is not specified, OpenDeploy tries each supported cipher, starting from the high-strength ones, until a compatible cipher is found with the remote OpenDeploy server. If no compatible is found, the deployment will fail.

The following example adds a 168-bit cipher and a low-strength cipher to the SSL data transfer key encryption code created in “Configuring OpenDeploy for SSL Data Transfer Encryption” on page 329:

<localNodehost="mars"sslCertificate="od-home/cert/odsrccert.pem"sslPrivateKey="od-home/cert/odsrckey.pem"sslCaCertificate="od-home/bin/demoCA/certs/cacert.pem"sslVerifyPeer="request"sslCiphers="EDH-RSA-DES-CBC3-SHA:DES-CBC-SHA"/>

331

Encryption

Testing the SSL Encryption Configuration

After you have configured OpenDeploy for SSL encryption, you should test it before performing an actual deployment. This section instructs you to modify the sample deployment configuration file test.xml. This sample deployment directs your OpenDeploy base server to deploy files to itself. Therefore, for this test, you will configure your base server configuration file to receive. However, you can also modify the test.xml file to deploy to other servers instead of, or in addition to, the sending server.

To test your SSL encryption configuration, follow these steps:



2. Make a copy of the file test.xml and rename it testssl.xml.

3. Modify the localNode element in the testssl.xml file as follows:

<localNodehost="host_name"sslCertificate="od-home/cert/odsrccert.pem"sslPrivateKey="od-home/cert/odsrckey.pem"sslCaCertificate="od-home/bin/demoCA/certs/cacert.pem"sslVerifyPeer="request"sslCiphers="EDH-RSA-DES-CBC3-SHA:DES-CBC-SHA"/>

Navigate to the following location:

od-home/(od-instance)/etc

4. Modify the localNode element in the base server configuration file (by default odbase.xml) as follows:

<localNodehost="host_name"sslCertificate="od-home/cert/odtgtcert.pem"sslPrivateKey="od-home/cert/odtgtkey.pem"sslCaCertificate="od-home/bin/demoCA/certs/cacert.pem"sslVerifyPeer="request"sslCiphers="EDH-RSA-DES-CBC3-SHA:DES-CBC-SHA"/>

If testssl.xml has been configured to deploy to other servers as well, each target’s server configuration file must be modified in this way.

5. Stop and restart the OpenDeploy service or daemon on each server whose base server or receiver configuration file was modified in the previous step. See “Stopping OpenDe-ploy” on page 21 and “Starting OpenDeploy” on page 17 for more information.

6. Run the testssl.xml deployment.

If the deployment runs successfully, the SSL encryption is correctly set up. If the deployment fails, or if the base server software does not appear to have started properly, refer to the OpenDeploy base server and deployment log files to determine and correct the problem. See Chapter 7, “Logging” on page 251 for more information.



Logging

You can verify that a deployment was run with SSL encryption by checking the receiver micro deployment log file. An entry indicating that SSL encryption was used in the deployment is written immediately below the date time stamp. For example:

v========== Start Log [Mon Jun 03 15:18:48 2002] ==========(2) Using SecureSocketsLayer protocol

See “Receiver Micro Deployment Log” on page 261 for more information on this type of log file.

Support for Third-Party Certificate Authority When Using SSL Encryption

You can use of a third-party certificate authority (CA) for SSL encryption as an alternative to the CA included with OpenDeploy. The procedure for using third-party CA differs depending on the type.

To use a third-party CA, follow these steps:

1. Generate a certificate signing request CSR/private key pair using the following command:

Windows — CA.bat -newreq or

UNIX — CA.sh -newreq

Using the -newreqþoption generates a CSR/private key pair (just like the -certall option) but does not sign the CSR with the local OpenDeploy CA, so no certificate is created. In contrast, the -certall command performs the certificate generation and then has the OpenDeploy CA sign the certificate.

The CSR and private key are both generated into the file newreq.pem.

2. Send the CSR to the third-party CA using one of the following methods:

If the CA can accept the CSR in PEM format (which is ASCII-based), open the newreq.pem file and copy the section bounded by "-----BEGIN CERTIFICATE REQUEST-----" and "-----END CERTIFICATE REQUEST-----" (including those lines). Use the third-party’s approved method to send them the CSR, such as in an email message, or through a Web form.

If the CA requires the CSR be submitted in DER format (which is binary-based), you must convert the newreq.pem file to DER format by running the following command at the prompt:openssl req -config openssl.cnf -in newreq.pem -inform PEM -out

newreq.der -outform DER

Attach the converted newreq.der file to an email and send it to the third-party CA.

Upon receiving the CSR, the third-party CA will subsequently return the signed certificate and the CA’s own certificate.

333

Encryption

3. Get the new certificate and the CA certificate from the third party CA:

If the returned certificates are in PEM format, you can use them as-is by copying and pasting them into the files newcert.pem and cacert.pem.

If the returned certificates are in DER format, you must convert them to PEM format by running the following command at the prompt:openssl x509 -in CA_file.der -inform DER -out CA_file.pem

-outform PEM

where CA_file represents the names of the new certificate or CA certificate file as appropriate.

4. Update the localNode element in base server, receiver, and deployment configuration files as necessary to reference to your signed certificate, your private key, and the third-party CA's certificate. For example:

<localNodehost="mars"sslCertificate="path_to_third-party_signed_certificate"

sslPrivateKey="path_to_local_generated_key (ex. newreq.pem from step 1)"sslCaCertificate="path_to_third-party_CA_certificate"...>

Refer to Chapter 8 “Encryption” in the OpenDeploy Administration Guide for more information on configuring and using SSL encryption.


Chapter 10


This chapter describes the Deployment Configuration Composer, and how to use it to create complete functional deployment configurations through the OpenDeploy user interface. Although the ability to write and understand XML code is not required to create and edit deployment configurations using the Deployment Configuration Composer, it is recommended that you review the features and functionality described in Chapter 2, “Deployment Types” and Chapter 4, “Deployment Features” prior to creating and editing any new or existing deployment configurations.

Deployment Configuration Composer

The Deployment Configuration Composer is a tool within the OpenDeploy user interface for creating new deployment configurations and editing existing ones. You can author or edit the configuration of any deployment that resides in the od-home/(od-instance)/conf directory, and that conforms to XML-based structure used in OpenDeploy 5.x deployment configurations.

The text boxes, lists, and option buttons that appear in the Deployment Configuration Composer interface correspond to elements and attributes in the deployment configuration file. The values you input are added to the deployment configuration file. Any existing deployment configuration can be edited and updated using the Deployment Configuration Composer.

335


To access the Deployment Configuration Composer, follow these steps:



2. Select the OpenDeploy server on which the deployment configuration will reside from the Selected Server list.

3. Select the name of the deployment group in which the deployment configuration will reside from the Deployment Group list.


If you want to create a wrapper file that invokes a DataDeploy configuration, rather than a full-featured OpenDeploy deployment configuration, you can check the DataDeploy Wrapper box. The Deployment Configuration Composer displays a different set of configuration features. See “Creating DataDeploy Wrapper Files” on page 384 for more information on this feature.


Deployment Configuration Composer

4. Click New to open a new browser window containing the containing the Deployment Configuration Composer (Figure 2).

Figure 2: Deployment Configuration Composer

The deployment group in which the deployment configuration will reside is reflected in the title of the window. Since this deployment will reside directly within the conf directory, “/” is displayed.

To edit an existing deployment configuration, select that configuration from the Deployment list and click Edit to open the Deployment Configuration Composer displaying the deployment configuration you selected.

Tree and Errors Tabs

The Deployment Configuration Composer contains Tree and Errors tabs on the left that display either a tree of configuration elements from which you can select, or a list of errors that display omissions of required information in your deployment configuration (Figure 3).

Figure 3: Tree and Errors Tabs

337


Tree Tab

The Tree tab displays the required and optional elements that make up the deployment configuration. Those elements in red are required to be completed before the configuration is done. After the information corresponding to a red element entry has been provided, the entry will turn blue.

Values contained in brackets ([ ]) reflect either a unique name value you assign them, for example:

Deployment Configuration [MYCONFIGURATION]

or the numbered occurrence of that elements, for example:

Filesystem [2]

When you complete adding information to a window in the Details pane, you can display the previous window by clicking the Up button. You can also display another window by selecting its entry in the Tree pane. When you provide names for elements, such as the definition element, that name is displayed next to its element in the Tree tab.

Errors Tab

The Errors tab displays error messages associated with any elements, attributes, or values that are missing or incorrect. You then must complete the required information and save the file again. When you save a deployment configuration, the Errors tab will automatically display any associated errors.

Details Pane

Selecting an entry in the Tree tab displays the corresponding window in the Details pane on the right of the browser window. Each window contains text boxes, buttons, drop-down lists, and other features which correspond to attributes in the deployment configuration. In some cases you must enter values for these attributes. In other cases, you have the option of providing a value, or allowing OpenDeploy to use its default values. Those attributes with a red asterisk (*) to the left denote required attributes for you to complete. In some cases, you can access a window in the Details pane either by selecting an entry in the tree, or by clicking a button in another Details pane window.


Types of Deployment Configuration Settings

Types of Deployment Configuration Settings

Deployment configuration settings fall under the following categories:

Global settings — configuration applies to the deployment as a whole. These settings include logging, nodes and node farms, transactional capability, and Deploy and Run scripting.

Definition settings — configuration applies to the specified definition element, which consists of a source/target pairing and its associated rules. These settings include the source and target areas, filters, and deployment rules.

Global Deployment Settings

Global deployment settings apply to all sources, targets, and deployed files included in the deployment. The following required tasks apply:

Name the deployment.

Verify or change the source host name.

Name your default node farm element.

Assign one or more target hosts listed in your nodes configuration file to each node farm.

Indicate whether or not the deployment is transactional.

You can apply perform these optional tasks:

Set your log rules.

Configure encryption.

Add and name any additional node farm elements.

Enter the name of the deployment that your target host will run after receiving your deployed files. Also indicate whether the target host will invoke a new deployment if your deployment is not successful. These tasks are required for multi-tiered deployments only.

Assign Deploy and Run capabilities as necessary, including those scripts that trigger upon the deployment of particular files, directories, or deployments.

339


Definition Settings

A deployment configuration contains one or more definition elements. Each definition element contains additional elements and attribute values that identify the source locations where deployed files originate, and the target location where those deployed files are received. For comparison-based deployments, those file locations participating in the deployment also are specified. Any rules establishing the deployment eligibility criteria of the files are also contained within the definition.

The following required tasks apply to each instance of the definition element in your deployment configuration:

Name the default definition element.

Indicate whether the definition is a forward or reverse deployment.

Specify the type of location (file system or TeamSite area) where the files to be deployed reside on the source host.

Enter the path to the source file location, including previous TeamSite area or file list path.

Enter any subdirectories within the specified source file location that further define where the source files reside. If you do not wish to further refine the area specification, you must enter the value “.” to indicate that no subdirectory is specified.

Enter the path to the target file location.

You can also apply these optional tasks:

Add and name any additional definition elements.

Add and configure any file path or pattern exclusion rules, and whether or not to follow symbolic links during the deployment.

Configure any target area overrides for deployments with multiple source area locations. Apply any transfer, comparison, or permission rules to those files deployed to this alternate area.

Add and configure any additional source file locations.

Configure any comparison, transfer, or permission rules for the deployment.

Configure any source- or target-side filters.


Creating a New Configuration


The following section leads you through the process of creating a new deployment configuration using the Deployment Configuration Composer. Each major task is separated to make the procedure easier to learn.

To create a new deployment configuration using the Deployment Configuration Composer, follow these steps:

1. Select Configurations > View Configurations to display the Deployment Configuration window.

2. Select the OpenDeploy server on which your new deployment configuration will reside from the Selected Server list.

If you want to create a wrapper file that invokes a DataDeploy configuration, rather than a full-featured OpenDeploy deployment configuration, you can check the DataDeploy Wrapper box. The Deployment Configuration Composer displays a different set of configuration features. See “Creating DataDeploy Wrapper Files” on page 384 for more information on this feature.

3. Click New. A new browser opens containing the Deployment Configuration Composer. The Deployment Configuration window (Figure 4) is displayed within the Deployment Configuration Composer. Here is where you will begin creating your new deployment configuration.


341


Naming the Deployment Configuration

Enter the file name of the deployment configuration in the File Name box.

You can enter a file name of any length up to the limit supported by the host operating system. Deployment configurations residing on UNIX hosts cannot have spaces in the file names. Those running on Windows hosts may contain spaces. It is not necessary to include the .xml extension in the file name you enter. The Configuration Composer will automatically add that extension when you save the file.

Specifying the Parameter Namespace

As an option, you can specify the parameter namespace for use in parameter substitution in the Parameter Namespace box. The parameter value is prepended with the namespace to get a fully-qualified parameter name. The fully-qualified parameter name is used to look up substitution values available in the closest scope. If no parameter namespace is specified, the parameter is considered to be in the global namespace.

See “Parameter Namespaces” on page 207 for more information.

Specifying the Log Rules

The log rules in a deployment configuration determine the maximum size a log file can grow before that file is closed to new entries, and a new log file is started. This is known as the rollover threshold. You can also specify whether you want the logging levels to be normal or verbose. See Chapter 7, “Logging” on page 251 for a complete description on OpenDeploy logging.

The default settings for Log Rules comes from the base server and receiver configuration files, however you can provide specific values for your deployment by clicking the New button associated with the Log Rules to display the Log Rules window (Figure 5).

Figure 5: Log Rules Window

You can also select the Log Rules entry in the Tree. Here you can set your own maximum log file size and logging level. You can input the following values in the Log Rules window:

Maximum Size box — enter the rollover threshold value. You can specify different byte measurements in the value, including megabytes (mb), kilobytes (kb), and bytes (b). For example:

10mb or

10000kb or

10000000b



If you enter a numerical value to fail to provide the measurement indicator, OpenDeploy will default to bytes (b). However, the minimum allowable size is 100 KB, or 102400 bytes. Setting a value smaller than this will be overridden with the default minimum when the deployment is run. See “Logging Configuration Settings” on page 263 for more information on OpenDeploy default logging values and rules.

Level options — select the level and type of logging OpenDeploy will perform:

verbose — logs a high level of detail on deployment events as they occur. This logging level is best suited for troubleshooting deployment problems or evaluating deployment performance. Verbose logging can create very large log files. This is the default logging level.

normal — logs standard status and error messages. In most cases, this level of logging provides sufficient detail to meet your needs.

Click Up when you are done with the Log Rules window to return to the Deployment Configuration window.

Specifying logging rules in the Deployment Configuration Composer is optional. If no logging levels are specified, OpenDeploy will use the logging levels present in the base server configuration if present, or use the following default settings:

Maximum Size (rollover threshold): 32 MB

Level: Verbose

Refer to “Logging” on page 134 in the OpenDeploy Installation Guide for more information.

Verifying or Changing the Source Host Name

Your deployment configuration must include the name of your OpenDeploy server host. This name can either be its resolvable host name or its IP address. Click the Edit button associated with the Local Host in the Deployment Configuration window to display the Local Node window (Figure 6).

Figure 6: Local Node Window

Enter the appropriate host name in the Host box. Typically this would be the host on which you are running OpenDeploy, but it could be another host name, for example, if you are authoring a deployment configuration you intend to use on another OpenDeploy server host.

343


Configuring the Concurrency Management Settings

You ca set both a polling interval for the blocked deployment and a timeout amount for the deployment in the Local Node window by configuring the following items:

blockMaxWaitTime box — specify the time interval in seconds that the deployment leg waits to check for path availability. The default value is 1800.

blockCheckInterval box — specify the maximum time in seconds that the deployment leg waits for a target directory to become available to receive the deployed files. The default value is 30.

See “Configuring Concurrency Management Settings” on page 88 for more information.

Specifying the Connection Timeout Level

You can specify the time allowed for a socket connection between the sender and the targets in a deployment to time out due to inactivity in the Timeout box in the Local Node window. A value of 0 indicates no timeout. See “Specifying the Connection Timeout” on page 87 for more information.

Specifying Deployment Encryption

Also present in the Local Node window (Figure 6) is your deployment encryption settings. If you want to use encryption with your deployment configuration, you must specify it here in the Encryption list.

SSL Attributes — symmetric key encryption that uses the secure sockets layer (SSL) key certificate.

Key File — 40-bit symmetric encryption that uses a key file.

If you select an encryption option, the following additional configuration attributes for that option will be displayed in the window for you to complete. See Chapter 9, “Encryption” on page 317 for more information on how encryption in OpenDeploy works.



SSL Attributes

The following attributes are displayed when you select the SSL Attributes encryption option (Figure 7):

Figure 7: SSL Attributes

Certificate box — enter the absolute path to the SSL public key certificate. This attribute is required for using asymmetric key encryption.

Private Key box — enter the absolute path to the SSL private key certificate. This attribute is required for using asymmetric key encryption.

CA Certificate box — enter the absolute path to the certificate authority. This allows OpenDeploy to authenticate the source from which the public and private key pairs for the source and target hosts are derived. This attribute is required for using asymmetric key encryption.

Ciphers box — enter the SSL ciphers to use. Multiple ciphers must be separated by colons (“:”). For example:

EDH-DSS-DES-CBC3-SHA:EXP-EDH-DSS-DES-CBC-SHA

This attribute is optional. Use of asymmetric encryption does require the use of ciphers.

Verify Peer list — select which of the following conditions apply in regards to the verification that the certificate authority for each public and private key pairs comes from the same source. This source is the value specified in the sslCaCertificate attribute.

none — no verification is performed. This is the default value.

request — verification is performed if the certificate/key pair exists on the peer of the host making the authentication request before the deployment can occur.

require — verification must be performed, and the certificate/key pair must exist on the peer of the host making the request before the deployment can occur.

345


Key File

The following attributes are displayed when you select the Key File encryption option (Figure 8):

Figure 8: Key File Attributes

Key File box— specifies the absolute path to the key file that provides the weak 40-bit symmetric encryption. For example:

C:\secure\MyKeyFile.txt or

/secure/MyKeyFile.txt

Click Up when you are done with the Local Node window to return to the Deployment Configuration window.

Specifying the File Transport Buffer Size

You can set a default buffer size in bytes for transporting files from your OpenDeploy source server, allowing you to “throttle” the bandwidth consumption on a per-deployment basis.

Click the New button associated with the Transport Properties to display the Transport Properties window (Figure 9).

Figure 9: Transport Properties Window

The Transport Properties contains the Name attribute, whose value is fixed as OD.

Enter an amount in bytes in the Buffer Size box. This value will serve as the default buffer size for transporting files.

See “Setting the File Transport Buffer Size (Bandwidth Throttling)” on page 196 for more information.



Naming the Replication Farm Element

The replication farm is an element in the deployment configuration that represents a collection of one or more target hosts. You must give each replication farm a unique name.

Click the Edit button associated with the Replication Farms to display the Replication Farms window (Figure 10).

Figure 10: Replication Farms Window

Here you must enter a unique name for your replication farm set in the Name box, for example:

MYREPLICATIONFARM

If you want more than one replication farm in your deployment configuration, click New Replication Farm to add another Replication Farms entry. You must provide a unique name for each replication farm in your deployment configuration.

You can assign a quorum value for each replication farm in the associated Quorum box. The quorum value specifies the number of target hosts that must successfully receive their deployments for the overall deployment to be considered successful. A transactional fan-out deployment whose quorum value was not met would be rolled back, even if some of the targets received their deployments successfully.

Adding Target Host Nodes to the Replication Farm Element

After you have named your replication farm elements, you must assign individual target host nodes to each one. Click the Edit button associated with a farm entry in the Replication Farms window to display the Replication Farm window for that particular replication farm(Figure 11).

Figure 11: Replication Farm Window

Here you can select those target hosts listed in your nodes configuration file (by default odnodes.xml) from the Node list. If you want to assign more than one target node to the replication farm element, click New Node Ref to add another entry.

347


Assigning Next-Tier Deployments to Target Hosts

If you intend for one or more of your deployment target hosts to redeploy the files it receives, you can configure that target host to trigger a specific deployment of its own upon receipt of the initial deployed files. This is part of a next-tier deployment. Any target you assign a next-tier deployment must have the base server software installed, and be able to deploy files to targets of its own.

Click the Edit button associated with your node entry in the Farm window to display the Node Ref window (Figure 12).

Figure 12: Node Ref Window

Enter the name of the deployment you want the associated node to run following receipt of the initial deployment in the Deployment box. The deployment you enter must be present in the target host.

If you select the yes option under Invoke On Success, then the next-tier deployment will only be run if the target host receives the first deployment successfully.

If the target is part of a multi-tiered deployment, and you want its files restored to its previous state in the event the multi-tiered deployment is unsuccessful, select the yes option under Multitier Transactional.

Click New Next Deployment if you want to assign another next-tier deployment to your target host. You can also select a different target host from the Node list to which you can associate your next-tier deployment.



Specifying a Transactional Deployment

A transactional deployment will automatically roll back a deployment and restore the target host’s files to their previous states in the event the deployment is not completely successful. This feature is particularly useful if you are deploying to multiple targets simultaneously, and it is important that all the target hosts contain the exact same files. See “Using Example and Sample Configurations” on page 143 for more information.

Select Deployment from the tree to display the Deployment window (Figure 13).

Figure 13: Deployment Window

To make your deployment transactional, click the yes button associated with the Transactional feature in the Deployment window.

Setting Deploy and Run

Deploy and Run is an OpenDeploy feature that allows you to run an external script during a deployment when one or more triggers apply. These triggers can include when a certain individual or category of directories or files are deployed, or when a particular deployment itself is run. Deploy and Run scripts associated with these triggers can be set to run on either the source host running the deployment, the host receiving the deployed files. They can also be set to trigger on the success of a deployment, its failure, or both. See “Utilizing the Delivery Adapter Framework” on page 208 for more information on this feature.

Assigning Deployment-based Deploy and Runs

You can assign a deployment-based Deploy and Run to a deployment by clicking New DNR Deployment Job in the Deployment window. This results in additional attributes being displayed for configuring a Deploy and Run (Figure 14).

Figure 14: Deployment Window with Deploy and Run Attributes Displayed

349


Select the target or source option under location to indicate on which end of the deployment the Deploy and Run will run.

Select the before or after option under when to indicate when during the deployment the Deploy and Run will run.

Select the appropriate option from the state list to indicate whether the Deploy and Run script should run as a result of the success or failure of the deployment, or whether it should always run in either case. If the when option is set to before, then the state attribute is implicitly set to always, because there has been no deployment yet to determine success or failure.

Click Edit to display the DNR Deployment Job window, where you can configure your deployment-based Deploy and Run. See “DNR Deployment” on page 354 for more information.

Click Delete to remove the associated Deploy and Run configuration.

Assigning Other Deploy and Runs Types

You can assign file- and directory-based Deploy and Runs, as well as deployment-based ones, in the Deployment Task window (Figure 15).

Figure 15: Deployment Task Window

The Deployment Task window is accessible by selecting Deployment Task from the tree, or by clicking the Edit button associated with each definition entry in the Deployment window.

Select the definition element to which you want to associate the Deploy and Run by selecting its name from the Definition list. Click New to display additional Deploy and Run attributes in the Deployment Task window (Figure 16).

Figure 16: Deployment Task Window with Deploy and Run Attributes



The Deploy and Run feature includes the following options:

DNR File — select to specify under what conditions deployed files can trigger a Deploy and Run script.

DNR Directory — select to specify under what conditions deployed directories can trigger a Deploy and Run script.

DNR Deployment — select to specify under what conditions the running of a particular deployment can trigger a Deploy and Run script.

Select the appropriate choice from the Type list and click New DNR Type to add an entry for that Deploy and Run element. You can create elements for DNR File, DNR Directory, DNR Deployment, in any number and combination (Figure 17).

Figure 17: Deployment Task Window with Multiple Deploy and Run Elements

DNR File

Clicking the Edit button associated with a DNR File entry displays the DNR File window (Figure 18).

Figure 18: DNR File Window

The DNR File window contains the following attributes:

Location option — this option is fixed as target, indicating the script will take place on the target host.

When option — select whether the script should be executed before or after the deployment of the particular file.

State list — indicates whether the Deploy and Run script should run as a result of the success or failure of the deployment, or whether it should always run in either case.

351


If the When option is set to before, then the State attribute is implicitly set to always, because there has been no deployment yet to determine success or failure.

File Mask box — enter the regular expression specifying the deployed files that will trigger the script. If you entered the following value:

\.html$

any deployed file with the file extension .html will trigger the Deploy and Run script.

Command box — enter the command where OpenDeploy can start a Deploy and Run script, as well as any accompanying flags or options. You can also specify an executable invocation line. For example:

C:\bin\email_to_admin.bat -user [email protected] or

/bin/mail [email protected] < /tmp/message.txt

If the command you are going to run requires a scripting engine, the scripting engine must be on the PATH of the user (or system, on Windows) who will be running the script or specified with a full path). For example:

/bin/sh /usr/local/bin/email_to_admin.sh -u [email protected] or

/usr/local/bin/iwperl /path/to/script.pl

As box — enter a different user name or user ID under which you can run the script. If you entered the following value:

rroe or

100

you could run the script as rroe rather than as your regular user name. By default, the script runs as the user who invokes OpenDeploy, who will need to be root for most purposes.

This feature applies to UNIX hosts only. On Windows hosts, this feature always runs as Default User.

Where box — enter the path to the location where the Command attribute value is to be run. For example:

/tmp or

C:\temp


The Where attribute is optional. If you do not specify a value, the process takes place in the root directory.

Asynchronous option — select yes to run the script asynchronously or no not to. Exercise caution when using this mode, as it could cause many scripts to be run simultaneously. The output from scripts run asynchronously is not captured.



DNR Directory

Clicking the Edit button associated with a DNR Directory entry displays the DNR Directory window (Figure 19).

Figure 19: DNR Directory Window

The DNR Directory window contains the following attributes:

Location option — this option is fixed as target, indicating the script will take place on the target host.

When option — select whether the script should be executed before or after the deployment of the particular directory.

State list — select whether the Deploy and Run script should run as a result of the success or failure of the deployment, or whether it should always run in either case.


Directory Mask box — enter the regular expression specifying the deployed directories that will trigger the script. If you entered the following value:

cgi-bin$

any deployed directory in the deployment path named cgi-bin will trigger the Deploy and Run script.







353



rroe or

100




/tmp or

C:\temp




DNR Deployment

Clicking the Edit button associated with a DNR Deployment entry displays the DNR Deployment window (Figure 20).

Figure 20: DNR Deployment Window

The DNR Deployment window contains the following attributes:

Location option — select whether the Deploy and Run script is taking place on the source or target host.

When option — select whether the script should be executed before or after the deployment of the particular file.



State list — indicates whether the Deploy and Run script should run as a result of the success or failure of the deployment, or whether it should always run in either case.









rroe or

100




/tmp or

C:\temp




355


Deleting Deploy and Run Entries

Each Deploy and Run element has associated attributes that you can display the complete by clicking the Edit button associated with the specific Deploy and Run element. If your deployment already has a Deploy and Run element configured, a Delete button will be displayed in place of the New button. Click this Delete button to delete all of the Deploy and Run elements you have created for the associated definition. If you want to delete specific Deploy and Run elements, but leave other intact, click the Delete button of the associated Deploy and Run element entry.

Specifying a Routed Deployment

By default, deployments you create in the Deployment Configuration Composer are not routed deployments, However, you can specify the deployment as being a routed deployment by selecting Routed Deployments from the Deployment Type list in the Deployment Configuration window (Figure 21).

Figure 21: Selecting Routed Deployment from Deployment Type List

When you click the Select button after select Routed Deployment, the Routed Deployment window appears (Figure 22).

Figure 22: Routed Deployment Window

You must provide a name for the route definition in the Route Definition box. For example, MYROUTEDEF.

You select whether (yes) or not (no) the following features are enabled in the deployment configuration or not:

useServerNodeHost — allows you to use the localHost element’s host attribute value contained in the initial deployment configuration, rather than the one in the sending server’s configuration file. See “Specifying a Common Host for Simplified Checking” on page 167 for more information on this feature.

Transactional — the deployment is transactional. “Specifying a Transactional Deployment” on page 349 for more information.



The Routed Deployment window contains other items regarding deployment tasks and Deploy and Run deployment jobs. See “Setting Deploy and Run” on page 349 for more information.

Naming and Adding Definitions

A definition element in a deployment configuration specifies each pairing of one or more file system locations or TeamSite areas residing on the source host with a single target location that will receive the deployed files. In the case of file system comparison deployments, the files residing in the target location will also be compared with those in the source host file system location. You can have more than one definition element in a deployment configuration, and each one must have a unique name.

Enter a unique name for your definition in the Definition box in the Deployment Configuration window (Figure 4), for example:

MYDEFINITION

If you want more than one definition in your deployment configuration, click New Definition to add another Definition entry. You must provide a unique name for each definition in your configuration.

Selecting the Definition Type

Each definition within a deployment can be one of the following types:

Forward Definition — the deployment originates at source host (usually a development server) and sends files to a receiving host (usually a production server). This type of deployment definition follows the standard development workflow.

Reverse Definition — the deployment originates at a receiving host (usually a production server) and deploys files back to the source host (usually a development server). This type of deployment definition will resynchronize the files between a development server and a production server if the production server has its files modified outside the standard workflow. See “Reverse Deployments” on page 168 for more information

You can select the definition type in the Definition window (Figure 23).

Figure 23: Definition Window

Select Definition from the tree to open this window. You can also click the Edit button associated with your definition entry in the Deployment Configuration window (Figure 13).

357


Select the type of definition you want from the Definition Type list.


The source file location is where the deployable files reside on the source host. You can configure your source file location in the Source window. Select Source from the tree to display the Source window (Figure 24).

Figure 24: Source Window

You also can click the Edit button associated with the source in the Definition window (Figure 23). The contents of the Source window is determined by the type of deployment you are configuring.

Selecting the Source Architecture Type

With this release of OpenDeploy, a new architecture is being used in deployment configurations to specify the source file location. This new architecture is described in “Defining the Source File Location” on page 102.

If you are creating a new deployment configuration, select New Source from the Source Type list.

If you are editing an existing deployment configuration that uses the legacy architecture, select Legacy Source from the Source Type list. Selecting Legacy Source results in the Deployment Configuration Composer using the legacy method of composing the source file location. Refer to your legacy OpenDeploy release’s documentation for information on how to configure the source file location in the Deployment Configuration Composer using this architecture.

The rest of this section describes using the new source type.



Selecting the Source Repository Type

You can perform most types of deployment both from a file system location or a TeamSite area. Select this source repository type from the Type list:

fileSystem — source repository is a file system location

iwStore — source repository is a TeamSite area

Click the New Source Repository Type button after you make your selection from the Type list. The corresponding source repository objects are displayed in the Source window. Figure 25 shows an example where the fileSystem type is selected:

Figure 25: Source Window with File System Repository Selected

You can provide a name for this repository type entry in the Name box, for example, MYFILESYS. This value will appear in the deployment configuration file as the name attribute value for the fileSystem or iwStore element.

Selecting the Deployment Type

Click the Edit button in the Source window to display the fileSystem or iwStore window, depending on what source repository type you selected. Figure 26 shows an example of the fileSystem window.

Figure 26: fileSystem Window

Select the deployment type you want to configure from the Deploy Type list. You can select from the following options, depending on your source repository type:

RemoteDiff — directory comparison

FileList — file list

PayLoad — payload adapter-based

AreaDiff (iwStore only) — TeamSite comparison

359


Beneath the Deploy Type list is a table containing the deployment type entries. The attributes displayed vary with the type of deployment you select. For example, if you selected FileList, the following entry is displayed (Figure 27):

Figure 27: FileList Deployment Type Entry

4. Enter the attribute values for the deployment type entry.

Each deployment type entry has an associated Name attribute. Assign a unique name to each deployment entry you add. In addition, the following attributes are displayed for each deployment type:

RemoteDiff:

• Area — specify the full path to the source file system location or TeamSite area.

FileList:


• File Path — specify the full path to the manifest file.

AreaDiff (iwStore only)

• Area — specify the full path to the source TeamSite area.

• Previous Area — specify the full path to the previous TeamSite area.

PayLoad

• Area — specify the full path to the source file system location or TeamSite area. There are additional configuration tasks associated with payload deployment types. See “Configuring Payload Deployments” on page 362 before proceeding to the next step.

5. Click the New Source Deployment Type button to add another entry to the table. You can add as many entries as you want, but they must all be of the same deployment type. You cannot include a mix of deployment types in the same offer configuration file.

Configuring Multiple Source Entries

You can configure more than one source entry within a definition. However, by default, all source entries deploy to the same target location. You run the risk of overwriting your files if you have multiple sources deploying simultaneously to the same target location. Multiple sources can also cause problems if one or more have the doDeletes feature enabled. In most cases, you only want to configure a single source entry. The one exception is when you use the Target Rules feature to define a different target location. See “Defining Source-Based Overrides” on page 140 for more information.



Defining a Subdirectory Within the Source File Location

In some cases, you might want to further narrow the source file location for you deployment within the specified source file system location or TeamSite area. You can specify a subdirectory relative to the source file area by entering that directory path in the Path Specification window (Figure 28).

Figure 28: Path Specification Window

Select the Path Specification entry associated with your Source entry in the tree to display the corresponding Path Specification window. You can also click the Edit button in the corresponding source file entry.

Click Path to display the Path window (Figure 29).

Figure 29: Path Window

Enter the relative path within the specified file system location or TeamSite area. For example, if you wanted to deploy files from the directory monthly within the specified area, you would enter the following value in the Name box:

monthly

If you do not want to specify a subdirectory within your specified area, simply enter a period (“.”) in the Name box.

You can specify additional subdirectories within your source file area by clicking the New Path Specification button in your file system or TeamSite window. Each path specification entry you add will have a corresponding path element that you can access by clicking the corresponding Edit button.

Each path entry you add is displayed in the tree as a separate Path entry. Select the Path entry or click the Edit button associated with your path entry in the Path Specification window to display the Path window.You can apply filters that will exclude specified files and directories from deployments at the target (see next section).

361


Configuring Payload Deployments

If you select Payload as the deployment type and configured it as specified in step 4 of the previous section, there are additional tasks you must perform, starting in the payLoad element window (Figure 30).

Figure 30: payLoad Element Window

1. Click the payLoadRules Edit button to display the payLoadRules window (Figure 31).

Figure 31: payLoadRules Window

2. Select one of the following options from the PayLoad Rules list:

Customer Defined Rules — indicates a payload adapter is being used that does not support the OpenDeploy query syntax.

Query — indicates an adapter that supports the OpenDeploy query syntax is being used.

See “Providing Input to the Adapter” on page 125 for an overview of these options.

The option you select appears as an element entry in the tree. Select that element to display additional configuration windows. The following sections describe configuring each option.

Customer Defined Rules

If you are using an adapter that does not support the OpenDeploy query syntax, such as the GenericRetrievalExample adapter or the Intelligent Delivery module’s TQueryGenericRetrieval adapter, or an adapter that you provide yourself, you must construct the query as a CDATA string within the Customer Defined Rules window.



Selecting the Customer Defined Rules element in the tree displays the Customer Defined Rules window (Figure 32).

Figure 32: Customer Defined Rules Window

Here you must enter the constructed query as a CDATA string, for example:

<![CDATA[SELECT path FROM table1 WHERE name='jdoe']]>

See “Using a PCDATA String” on page 125 for more information.


If you are using an adapter that supports the OpenDeploy query syntax, such as the QueryRetrievalExample adapter or the Intelligent Delivery module’s TQueryGenericRetrieval adapter, you can construct the query using the OpenDeploy query syntax.

1. Select the Query element in the tree to display the Query window (Figure 33).

Figure 33: Query Window

Here you can construct your query using the OpenDeploy query syntax. See “OpenDeploy Query Syntax” on page 126 to familiarize yourself before beginning the query construction.

363


2. Select Predicate from the Query Item list to display a Predicate entry in the Query window (Figure 34).

Figure 34: Predicate Entry

3. Enter the operator and value information as described in “OpenDeploy Query Syntax” on page 126.

If you want to include multiple predicate elements linked with the AND or OR element, select And or Or from the Query Item list to display the associated window. Figure 35 shows an AND entry:

Figure 35: And Entry

4. Use of AND or OR requires that you include at least two predicate elements in your query. You cannot includes both AND and OR element in the same query.

5. Click the Edit button associated with a predicate element entry, either in the Predicate window, or in the AND or OR windows, to display the Predicate window (Figure 36).

Figure 36: Predicate Window

Here, the operator and value attributes associated with the predicate element are displayed. In addition, the Key: Edit button is present. Click Edit to display the Key window (Figure 37).

Figure 37: Key Window



6. Enter the metadata key name in the Key Name box. Select one of the following options from the Query Key Type list:

Text Type — indicates the value is text string.

Numeric Type — indicates the value is numeric.

Date Type — indicates the value is based on a specified date format. Selecting this option causes the Date Type and Date Format items to appear in the Key window (see below:

Date Type — select of the following options:

• date — reflects the day, month, and year; or

• timestamp — reflects the second, minute, hour, day, month, and year.

Date Format — enter the SimpleDateFormat Java class format for the date or timestamp (as specified by the Date Type box attribute), for example:

dd/mm/yyyy (indicates day/month/full year) orss/mm/hh/dd/mm/yyyyy


http://java.sun.com/j2se/1.3/docs/api/java/text/SimpleDateFormat.html

Payload Deployment Actions

When you specify the deployment type as a payload, you must indicate what kind of action OpenDeploy is to take

Select the Action element from the tree to display the Action window (Figure 38).

Figure 38: Action Window

Select one of the following options from the Name list:

deploy — indicates the files in the manifest are compared with the files in the target and, if appropriate, deployed. This is the default value. If no value is specified for the name attribute, OpenDeploy runs the deployment using the default value.

expire — indicates the files in the manifest are removed from the target file location. In this case, no comparison of these files with the target files occurs.


365


Applying Source-Side Filters

You can include filters that will exclude files and directories at the source host, based on patterns in their paths names or their file names. See “Filters” on page 175 for more information on this feature.

Source-side filters are configured in the Filter Set window (Figure 39).

Figure 39: Filter Set Window

Click the New button associated with Filter Set in the Path Specification window to display the Filter Set window. If filters are already configured, you can click the Edit button in the Path Specification window or select Filter Set from the tree to display the Filter Set window.

You can configure the following types and combinations of filters in the Filter Set window:

File system-based inclusion filters — filters that only include those items whose paths match one or more of the path values you specify. File system-based inclusion filters cannot be used in combination with any other filter type.

Pattern-based inclusion filters — filters that only include those items whose names match one or more of the regular expression values you specify. Pattern-based inclusion filters cannot be used in combination with any other filter type.

File system-based exclusion filters — filters that exclude those items whose paths match one or more of the path values you specify. File system-based exclusion filters can be used in any combination with pattern-based exclusion filters. They can also be used in combination with either file system- or pattern-based exception filters, but not both.

Pattern-based exclusion filters — filters that exclude those items whose names match one or more of the regular expression values you specify. Pattern-based exclusion filters can be used in any combination with pattern-based exclusion filters. They can also be used in combination with either file system- or pattern-based exception filters, but not both.

File system-based exception filters — filters that protect those items whose paths match one or more of the path values you specify from any exclusion filters that would otherwise eliminate the items from the deployment. They can be used in combination with both file system- and pattern-based exclusion filters, but not with pattern-based exception filters.

Pattern-based exception filters — filters that protect those items whose names match one or more of the regular expression values you specify from any exclusion filters that would otherwise eliminate the items from the deployment. They can be used in combination with both file system- and pattern-based exclusion filters, but not with pattern-based exception filters.



You can add file system- or pattern-based inclusion filters by selecting Include Path or Include Pattern, respectively, from the Filter Type list in the Filter Set window. You can add exclusion and exception filters by selecting Exclude and Except. The attributes associated with your selection are displayed in the Filter Set window.

File System-Based Inclusion Filters

Select Include Path from the Filter Type list to add a file system-based inclusion filter. Click Include New Path to display an Include Path filter entry (Figure 40).

Figure 40: File System-Based Inclusion Filter

Enter the path that all items must match to be included in the deployment in the Sub Path box. For example, to add a filter that would only include the contents of the directory reports/monthly within the specified area, enter the following value:

reports/monthly

The path you enter is relative to the local directory or TeamSite area on the source host containing the files to be moved. You can add additional file system-based inclusion filters by clicking New Include Path for each entry. You can delete any entry by clicking the associated Delete button.

You cannot use file system-based inclusion filters in combination with any other type of inclusion, exclusion, or exception filter.

367


Pattern-based Inclusion Filters

Select Include Pattern from the Filter Type list to add a pattern-based inclusion filter. Click Include New Pattern to display an Include Pattern filter entry (Figure 41).

Figure 41: Pattern-Based Inclusion Filter

Enter the regular expression that all items’ names must match to be included in the deployment in the Regular Expression box. For example, to add a filter that only includes files that end with the extension .txt within the specified area, enter the following value:

.*\.txt$

See “Supported Regular Expressions” on page 186 for more information on using regular expressions in deployment configurations.

You can add additional file system-based inclusion filters by clicking New Include Pattern for each entry. You can delete any entry by clicking the associated Delete button.

You cannot use pattern-based inclusion filters in combination with any other type of inclusion, exclusion, or exception filter.

File System-Based Exclusion Filters

Select Exclude and Except from the Filter Type list add any exclusion and exception filters. A file system-based exclusion filter entry is displayed by default (Figure 42).

Figure 42: File System-Based Exclusion Filter

Enter the path that all items must match to be excluded from the deployment in the Sub Path box. For example, to add a filter that ignores the directory WebFiles/working within the specified area, enter the following value:

WebFiles/working



The path you enter in the Sub Path box is relative to the local directory or TeamSite area on the source host containing the files to be moved. You can add additional file system-based exclusion filters by clicking New Exclude Path for each entry. You can delete any entry by clicking the associated Delete button.

You can use file system-based exclusion filters with other types of exclusion filters. You can also use them with either file system- or pattern-based exception filters, but not both. You cannot use pattern-based exclusion filters with any type of inclusion filter.

Pattern-Based Exclusion Filters

Select Exclude and Except from the Filter Type list add any exclusion and exception filters. Select Exclude Pattern from the Type list and click New Exclude Filter to add a pattern-based exclusion filter entry (Figure 43).

Figure 43: Pattern-Based Exclusion Filter

Enter the regular expression that all items’ names must match to be excluded from the deployment in the Regular Expression box. For example, to add a filter that ignores any file that ends with the extension .html within the specified area, enter the following value:

.*\.html$


You can add additional pattern-based exclusion filters by clicking New Exclude Path for each entry. You can delete any entry by clicking the associated Delete button.

You can use pattern-based exclusion filters with other types of exclusion filters. You can also use them with either file system- or pattern-based exception filters, but not both. You cannot use pattern-based exclusion filters with any type of inclusion filter.

369


File System-Based Exception Filters

Select Except Path from the Except Filter Type list displayed your exclusion filters to add a file system-based exception filter (Figure 44).

Figure 44: File System-Based Exception Filter

Enter the path that all items must match to be protected from any exclusion filters in the Sub Path box. For example, to add a filter that protects the directory WebFiles/reports/external within the specified area, then you would enter the following value:

WebFiles/reports/external

The path you enter in the Sub Path box is relative to the local directory or TeamSite area on the source host containing the files to be moved.

You can add additional file system-based exception filters by clicking New Except Path for each entry. You can delete any entry by clicking the associated Delete button.

You can use file system-based exception filters with any combination of exclusion filters. You cannot use them with other types of exception filters, or any type of inclusion filters.

Pattern-Based Exception Filters

Select Except Pattern from the Except Filter Type list displayed your exclusion filters to add a pattern-based exception filter (Figure 45).

Figure 45: Pattern-Based Exception Filter



Enter the regular expression that all items’ names must match to be protected from any exclusion filters in the Regular Expression box. For example, to add a filter that protects any files with the extension .pdf, enter the following value:

.*\.pdf$


You can add additional pattern-based exception filters by clicking New Except Pattern for each entry. You can delete any entry by clicking the associated Delete button.

You can use pattern-based exception filters with any combination of exclusion filters. You cannot use them with other types of exception filters, or any type of inclusion filters.

Following Source-Side Symbolic Links in Deployments

You can configure a deployment running on a UNIX server to deploy files referenced in symbolic links, a procedure known as following links. This feature is not available with OpenDeploy running on Windows. See “Deploying Symbolic Links” on page 201 for more information on this feature.

You can configure your UNIX-based OpenDeploy server host to follow links on the source side by enabling the feature in the Source Transfer Rules window (Figure 46).

Figure 46: Source Transfer Rules Window

You can display the Source Transfer Rules window by clicking the associated New or Edit button in the Path Specification window (Figure 28). You can also select Source Transfer Rules from the tree if an entry already exists.

Select the yes option in the Source Transfer Rules window to enable the Follow Links feature.

You can also enable the follow links feature at the target side by enabling the Follow Links attribute in the Transfer Rules window. See “Applying Transfer Rules” on page 376 for more information.

371


Designating Alternate Targets from the Source

You can associate a target area with a particular source in a file system comparison deployment with multiple sources. This feature provides the ability to create multiple source/target pairings for a single deployment. See “Defining Source-Based Overrides” on page 140 for more information on this feature.

You can designate an alternate target location for a set of deployed files through the Target Rules window (Figure 47).

Figure 47: Target Rules Window

You can display the Target Rules window by clicking the associated New or Edit button in the Path Specification window (Figure 28). You can also select Target Rules from the tree if an entry already exists.

The Target Rules window contains the Area box, where you can enter the path for an alternate target file location. There are also buttons for other features that apply only to those files that are being deployed. Each of these features is described separately.

Enter the full path to the alternate target location for the source files that use this feature. For example, if you wanted to deploy to the following location:

D:\metadata\files

enter that path in the Area box.

Other features accessible in the Target Rules window that you can apply to alternate targets are listed below:

Filter Set — see “Applying Target-Side Filters” on page 381.

Transfer Rules — see “Applying Transfer Rules” on page 376.

Comparison Rules — see “Applying Comparison Rules” on page 375.

Permission Rules — see “Applying Permission Rules” on page 378.




The target file location is the location on the target host where deployed files reside following the deployment. The target file location can be a file system location or a TeamSite workarea .

In directory comparison deployments, any files residing in the target directory location are compared with equivalent files in the source file location, and the differences (based on the criteria for deployment) are deployed to the target. In TeamSite comparison and file list deployments, the target file location is simply a repository for the deployed files. Any files residing in the target file location are excluded from the comparison of TeamSite areas on the source host. Files residing in the target file area prior to running the deployment can be overwritten by like-named deployed files.

By default, one target directory location is associated with each definition element in a deployment configuration. If you have multiple sources within a definition, they will (by default) deploy files to the same target directory location. You can use the target rules option to create alternate target directory locations on a source-by-source basis. See “Designating Alternate Targets from the Source” on page 372 for more information on that feature.

The target file location is defined in the Target window (Figure 48).

Figure 48: Target Window

You can display the Target window by clicking the associated Edit button in the Definition window (Figure 23), or by selecting the Target entry in the tree.

373


Specifying the Target Type

You specify whether the target type is a file system or a TeamSite work area. Select the appropriate option in the Target window’s Target Type list and click Select. Depending on which option you chose, the associated Filesystem or TeamSite window is displayed.

File System

Enter the target file system location in the Filesystem window’s Area box (Figure 49).

Figure 49: Filesystem Window

For example, if you entered the value /website/files, then each target in the deployment would received the deployed files in that location, unless that target location is overridden by another in the configuration.

TeamSite

Enter the TeamSite workarea in the TeamSite window’s Area box (Figure 50).

Figure 50: TeamSite Window

In addition to entering the TeamSite workarea location, you can also specify whether or not to include any associated TeamSite extended attributes (EAs) with the deployed files. If you specify yes for the applyExtAttrs option, the EAs associated with the TeamSite files are included in the deployment. If you specify no, the EAs are not included in the deployment.

Defining a Subdirectory Within the Target TeamSite Location

You can also configure path specification settings for the TeamSite target location in a manner similar to the source file location. Click the Edit button associated with the Path Specifications to display the Path Specification window. See “Defining a Subdirectory Within the Source File Location” on page 361 for more information on configuring the path specification.



Specifying the Target Replication Farm

Each target must be associated with a particular replication farm. Enter the name of the appropriate replication farm in the Replication Farm box. The replication farm contains one or more individual target host nodes that will receive the deployed files. The information you enter into the Target window determines the target file location on the target host nodes making up the members of the replication farm.

Specifying the Target Replication Farm Location

You must specify where the target replication farm you entered resides. Target replication farms can exist either in the deployment configuration itself, or in the sending server’s nodes configuration file (by default odnodes.xml). You must specify the location in the Replication Farm Link window (Figure 51), which you can display by clicking the associated Edit button in the Target window.

Figure 51: Replication Farm Link Window

Select one of the following options from the Replication Farm Source list and click Select:

internal — the replication farm is configured inside the deployment configuration.

external — the replication farm is configured in the nodes configuration file.

Applying Comparison Rules

Comparison rules define the rules that OpenDeploy uses when it compares files contained in a file system. The type and platform of the file system determines the criteria available. These rules are used to determine eligibility of files for deployment. See “Comparison Rules” on page 187 for more information on this feature.

Comparison rules are defined in the Comparison Rules window (Figure 52).

Figure 52: Comparison Rules Window

You can display the Comparison Rules window by clicking the New or Edit button associated with Comparison Rules in the Target window (Figure 48), or by selecting its entry from the tree.

375


The Comparison Rules window contains the following options:

Date Different option — indicate whether or not a file should be deployed if there is any difference in file date (older or newer) between the source and target versions. This differs from the OpenDeploy default date-based comparison setting, where a file should be deployed only if the source file is newer than the target file.

Ignore ACLs option (Windows only) — indicate whether (yes) or not (no) to ignore differences in the Windows access control lists (ACLs) during the file comparison.

Ignore Modes option (UNIX only) — indicate whether (yes) or not (no) to ignore differences in the UNIX-based permission mode bits definitions during the file comparison.

Ignore User option (UNIX only) — indicate whether (yes) or not (no) to ignore differences in the UNIX-based user ownership during the file comparison.

Ignore Groups (UNIX only) option — indicate whether (yes) or not (no) to ignore differences in the UNIX-based group ownership during the file comparison.

Applying Transfer Rules

Transfer rules define the rules for moving files from the source host to the target host during the deployment. See “Transfer Rules” on page 190 for more information on this feature.

Transfer rules are defined in the Transfer Rules window (Figure 53).

Figure 53: Transfer Rules Window

You can display the Transfer Rules window by clicking the New or Edit button associated with Transfer Rules in the Target window (Figure 48), or by selecting its entry from the tree.

The Transfer Rules window contains the following options:

Do Deletes option — select whether (yes) or not (no) files and directories not present in the source host area will be deleted on the target host.



Don't Do option — select whether (yes) or not (no) to proceed with the deployment following the comparison. Deployment will not occur if this attribute is enabled. This is a good tool to use to check and compare files without actually performing a deployment.

Preserve ACLs option (Windows only) — select whether (yes) or not (no) to preserve the Windows access control lists (ACLs) when the files are moved.

Follow Links option — select whether (yes) or not (no) symbolic links on the target hosts will be followed when the files are moved.

Server Try Count box (Windows only) — enter the number of times OpenDeploy will attempt to deploy the file to the target host. This feature works in conjunction with Microsoft IIS, and is designed to accommodate times of heavy production server traffic.

Server Try Interval box (Windows only) — enter the amount of time in seconds OpenDeploy waits between deployment attempts. This feature works in conjunction with Microsoft IIS, and is designed to accommodate times of heavy production server traffic.

Server Try Disable Overwrite option (Windows only) — select whether (yes) or not (no) to disable the ability of OpenDeploy to deploy files to a server even if the svrTryCount and svrTryInterval elements are specified. This feature works in conjunction with Microsoft IIS, and is designed to accommodate times of heavy production server traffic.

Remove Read Only Attribute — select whether (yes) or not (no) a deployed file can overwrite its read-only target equivalent. If enabled, OpenDeploy removes the read-only attribute from the target file, allowing the deployment to occur.

Compression — select whether (yes) or not (no) to indicate whether content is compressed prior to be deployed.

Compression Level — enter the level of compression (0-9) OpenDeploy uses when compression is enabled. A value of 1 is the lowest level of compression, and 9 is the highest level. A value of 0 provides no compression at all.

377


Applying Permission Rules

Permission rules define the rules applicable to the permissions of deployed files and directories. See “Permission Rules” on page 193 for more information on this feature.

Permission rules are defined in the Permission Rules window (Figure 54).

Figure 54: Permission Rules Window

You can display the Permission Rules window by clicking the New or Edit button associated with Permission Rules in the Target window (Figure 48), or by selecting its entry from the tree.

Access options specific to UNIX are ignored when deploying to a Windows target host, and access options specific to Windows are ignored when deploying to a UNIX target host.

The Permission Rules window contains the following options:

Amask box (UNIX only) — enter the bit mask (in octal) to be ANDed with the permission bits of all files and directories. The amask octal value combines with the existing permission bit value of the affected file. If a file has the existing permission value of 664 (-rw-rw-r--) and the amask attribute as the following value:

amask="770"

then the resulting permission for that file (664 AND 770) following the deployment would be 660 (-rw-rw----).

Omask box (UNIX only) — enter the bit mask (in octal) to be ORed with the permission bits of all files and directories. The omask octal value combines with the existing permission bit value of the affected file. If a file has the existing permission value of 666 (-rw-rw-rw-) and the omask attribute as the following value:

omask="022"

then the resulting permission for that file (666 OR 022) following the deployment would be 644 (-rw-r--r--).



Directory box (UNIX only) — enter the permissions (in octal) given to all deployed directories. For example, if you wanted deployed directories to have the permission “drwxrwx---”, then the resulting value would be:

directory="770"

File box (UNIX only) — enter the permissions (in octal) given to all deployed files. For example, if you wanted deployed files to have the permission “-rw-rw-r-x” , then the resulting value would be:

file="665"

Group box (UNIX only) — enter the group assigned to all deployed files and directories. This attribute value must be a valid group name or group ID. For example:

group="tech_pubs" or

group="200"

You must also specify the user attribute if you use employ the group attribute.

User box (UNIX only) — enter the user who will own all deployed files and directories. This attribute value must be a valid user name or user ID. For example:

jdoe or

105

You must also specify the group attribute if you use employ the user attribute.

Change Access box (Windows only) — enter a value that modifies the access control lists (ACLs) so that specified users have the designated rights. The new access control entry (ACE) for each specified user allows only the specified rights, discarding any existing ACE. In the following example:

changeAccess="{ jdoe:W, tech_pubs:NONE }"

any existing ACEs for jdoe and tech_pubs are removed, jdoe is granted write access, and the group tech_pubs has no access at all. Any other access rights that may have existed for other users are left unchanged. See “Using OpenDeploy with ACLs” on page 198 for more information.

Set Access box (Windows only) — enter a value that replaces the ACLs for the deployed files and directories. In the following example:

setAccess="{ jdoe:ALL, tech_pubs:RX }"

the existing ACL is removed and the user jdoe is granted full access. The group tech_pubs has read access to the specified files. Any other access rights that may have existed for the file are removed. See “Using OpenDeploy with ACLs” on page 198 for more information.

379


User Translation

The User Translation feature (Figure 55) allows you to change user IDs (UNIX only) for deployed files. You can add and configure an unlimited number of user translations in your deployment. See “User and Group Ownership Transferal” on page 195 for more information on this feature.

Figure 55: User Translation Feature

The User Translation feature contains the following attributes:

New User Translation button — click to add a user translation entry.

From box — enter the existing source user or user ID (the identification number assigned to each user account within the UNIX server). For example:

jdoe or

105

To box — enter the new target user or user ID. For example:

rroe or

110

Delete button — click to delete a user translation entry.

Group Translation

The Group Translation feature (Figure 56) is where you can change group IDs (UNIX only) for deployed files. You can add and configure an unlimited number of group translations in your deployment. See “User and Group Ownership Transferal” on page 195 for more information on this feature.

Figure 56: Group Translation Feature

The Group Translation feature contains the following attributes:

New Group Translation button — click to add a group translation entry.

From box — enter the existing source group or ID (the identification number assigned to each group account within the UNIX server). For example:

tech_pubs or

100



To box — enter the new target group or ID. For example:

marketing or

200

Delete button — click to delete a group translation entry.

Configuring for Use with Adapters

You can configure the deployment for the enabling of an adapter (Java program) written to run in the Delivery Adapter Framework. A base server host can be configured to load and run the designated Java class (adapter) upon completion of any deployment it receives. After the content is received, the adapter can push the content somewhere else, such as to an edge server over HTTP. This functionality is available only for targets running the base server software, not the receiver software. See Appendix A, “Delivery Adapters” on page 439 for more information on this feature.

You can configure the enabling of an adapter in the Adapter Set window (Figure 57).

Figure 57: Adapter Set Window

You can display the Adapter Set window by clicking the New button associated with Adapter Set in the Target window.

The Adapter Set window contains the following attributes:

New Adapter button — click to display the attributes for the adapter.

Name box — enter the name of the Java class that implements the adapter.

Parameter box — specify the parameter for the adapter.

Delete button — click to delete the entry.

Applying Target-Side Filters

You can include filters that will exclude files and directories from being received by the target host, based on patterns in their paths names or their file names. See “Filters” on page 175 for more information on this feature.

Adding or modifying target-side filters is done by clicking the New or Edit button associated with the filter set in the Target window. Configuring these filters is done in a manner similar to that of source-side filters. See “Applying Source-Side Filters” on page 366 for more information on filter usage.

381


Saving the Deployment

When you have completed configuring your deployment, you must save it by clicking the Save button at the top of the Deployment Configuration Composer window. If any required items of information are missing, such as required attribute values, the Deployment Configuration Composer will display the appropriate error messages in the Error pane. See “Details Pane” on page 338 for an example.

Upon successfully saving the deployment, the configuration is displayed (Figure 58).

Figure 58: Example of Saved Deployment


Editing Deployment Configurations

Editing Deployment Configurations

You can use the Deployment Configuration Composer to edit existing configurations, even those that were not created using this tool. You can edit the configuration of any deployment that resides in the od-home/(od-instance)/conf directory, and that conforms to XML-based structure used in OpenDeploy 5.x deployment configurations.

To edit an existing deployment configuration, follow these steps:

1. Select Configurations > View Configurations to display the Deployment Configuration window.

2. Select the OpenDeploy server on which the deployment configuration will reside from the Selected Server list.

3. Select the deployment you want to edit from the Deployment list.

4. Click Edit to open a new browser window containing the containing the Deployment Configuration Composer. The elements and attributes for that deployment are displayed in the Details pane.

5. Modify your deployment using the methods described in this chapter.

6. Click Save to save your changes.

Editing Configuration From Previous OpenDeploy Releases

The Deployment Configuration Composer only generates deployment configurations compatible with this release of OpenDeploy. You can open deployment configurations from previous OpenDeploy 5.x releases, but they will be saved as files compatible for this release only.

If you want to modify a deployment configuration for use with an older version of OpenDeploy, you should open the file with a text or XML editor and make your changes manually.

383


Creating DataDeploy Wrapper Files

You can use the Deployment Configuration Composer to generate a DataDeploy wrapper file for invoking a DataDeploy configuration file, rather than for creating a full-featured OpenDeploy deployment configuration. A DataDeploy wrapper file simply contains the path to a DataDeploy configuration, and also some logging information. When a DataDeploy wrapper file is run (using the same methods as for running standard OpenDeploy deployment configurations), the referenced DataDeploy configuration is invoked.

Refer to the Database Deployment for OpenDeploy Administration Guide for information on how to use DataDeploy.

To create a DataDeploy wrapper file using the Deployment Configuration Composer, follow these steps:

1. Start creating a standard OpenDeploy deployment configuration using the Deployment Configuration composer. See “Creating a New Configuration” on page 341 for more information.

2. Check the DataDeploy Wrapper box and click New.

When you click New after enabling the DataDeploy wrapper feature, the Deployment Configuration Composer displays a different window (Figure 59) than for standard OpenDeploy deployment configurations.

Figure 59: Deployment Configuration Window for DataDeploy Wrapper File

3. Enter the name of the DataDeploy wrapper file in the File Name box.

4. Click the Edit button next to the dataDeploy label. The dataDeploy window appears (Figure 60).

Figure 60: dataDeploy Window


Editing Remote Upgrade Deployments

5. Enter the full path to the DataDeploy configuration file you want to invoke in the configFilePath box.

6. Specify the log rules for this file. See “Specifying the Log Rules” on page 342 for more information.

7. Click Save. The XML-based contents of the DataDeploy wrapper file are displayed (Figure 61).

Figure 61: XML-Based Contents of DataDeploy Wrapper File


The Deployment Configuration Composer can be used to edit deployment configurations associated with the remote upgrade feature such as the following:

Software distribution

License identification

License distribution

It is not recommended that you attempt to compose a new remote upgrade deployment using the Deployment Configuration Composer. However, you can edit those deployments that were generated through the remote upgrade windows in the user interface.

Using the Deployment Configuration Composer, you can access remote upgrade deployments in the following ways:

Selecting the deployment group and deployment from the Deployment Configuration window, similar to editing traditional deployments. See “Editing Deployment Configurations” on page 383 for more information.

Using the Remote Upgrade window, selecting the type of remote upgrade deployment you want to edit, and then Click the View button associated with the particular deployment. Clicking View displays the Deployment Configuration window, where you can click Edit to invoke the Deployment Configuration Composer.

Using the Deployment Configuration Composer to edit remote upgrade deployments is similar to that of traditional deployments. Each target of the remote upgrade tasks is represented by separate replication farms and definitions in the configuration. Certain elements and attributes displayed in the Deployment Configuration Composer are unique to remote upgrade configurations. The rest of this section describes those items.

385


Configuring Remote Action Requests

The Request Action window is where you can configure a remote action request from the sending server to the target servers.

To access the Request Action window, you must first open the Remote Action window (Figure 62). The Remote Action window is displayed when you click the New or Edit button for Remote Action in the Deployment Configuration window.

Figure 62: Remote Action Window

Click the Edit button to display the Request Action window ()

Figure 63: Request Action Window

The Request Action window contains the following attributes:

key — select one of the following options:

IW_GET_REMOTE_VERSION — requests the target host to get its OpenDeploy version and sends it back to the sender.

Remote upgrade deployments use this remote action request to verify that each target host has been successfully upgraded to the expected release. If a target host turns this remote action request off, the sending deployment will not be able to verify if the remote upgrade has successfully upgrade this server or not.

IW_GET_REMOTE_INFO — requests the target to collect information on its host that is used for licensing and sends it back to the sender.

The example deployment licidentification.xml, used to collect information from target hosts for licensing uses this remote action request. If a target host turns this remote action request off, the sending deployment will not be able to collect information needed for obtaining a license for this sever.

IW_DISTRIBUTE_LIC — requests the target host to allow the sender to add or update its OpenDeploy server's license file.This value also allows for the refeshing of its license information.

The example deployment licdistribute.xml, used to update licenses on target hosts, uses this remote action request. If a target host turns this remote action request off, the sending deployment will not be able to add or update its license.



Replication Farm Link — click the Edit button to display the Replication Farm Link window, where you can specify whether the replication farm containing the list of targets is contained in the deployment configuration itself (internal) or in the sending server’s nodes configuration file (external). See “Specifying the Target Replication Farm Location” on page 375 for more information.

Action Parameters — click the New or Edit button to display the Action Parameters window (Figure 64).

Figure 64: Action Parameters Window

Here you can configure or modify the following attributes:

Verify Upgrade — select whether (true) or not (false) to verify that the upgrade was successful. If the value is set to false then theIW_GET_REMOTE_VERSION will not check the version it received from the target against the string specified in the expected version parameter.

Expected Version box — enter the version you are expecting the remote OpenDeploy server to return. Use the format x.x.x.x.x, for example: 6.1.0.0.0.

Configuring Target Progress Checking

The Get Info window is where the polling properties for a remote action request from a sending server to the target servers are configured. Remote upgrade deployments use this to verify that each target hosts has been successfully upgraded to the expected release.

Figure 65: Get Info Window

You can access the Get Info window by clicking the New or Edit button associated with Get Info in the Deployment Task window, or by selecting the Get Info link under the Deployment Task heading in the tree.

The Get Info window contains the following attributes:

Check Interval in Mins box — enter the amount of time in minutes between polling of the target.

Max Iterations box — enter the number of times the target is to be polled for information before the deployment to that target quits.

387


request — click the Edit button to display the Request window. This window is described in the following section.

Initial Polling Request

The Request window (Figure 66) is where you can configure remote action request to perform in the polling.

Figure 66: Request Window

Note: Unlike the Get Info feature, this request is done one time only. The Get Info feature polls the target servers multiple times.

The request window has the following attributes:

key — specify one of the following values:

IW_GET_REMOTE_VERSION — requests the target host to get its OpenDeploy version and sends it back to the sender.

Remote upgrade deployments use this remote action request to verify that each target host has been successfully upgraded to the expected release. If a target host turns this remote action request off, the sending deployment will not be able to verify if the remote upgrade has successfully upgrade this server or not.

IW_GET_REMOTE_INFO — requests the target to collect information on its host that is used for licensing and sends it back to the sender.

The example deployment licidentification.xml, used to collect information from target hosts for licensing uses this remote action request. If a target host turns this remote action request off, the sending deployment will not be able to collect information needed for obtaining a license for this sever.

IW_DISTRIBUTE_LIC — requests the target host to allow the sender to add or update its OpenDeploy server's license file.This value also allows for the refeshing of its license information.

The example deployment licdistribute.xml, used to update licenses on target hosts, uses this remote action request. If a target host turns this remote action request off, the sending deployment will not be able to add or update its license.

Action Parameters — see “Configuring Remote Action Requests” on page 386 for more information on this attribute.


Chapter 11

Syndication

OpenDeploy supports the syndication of content through the optional Intelligent Delivery module. Syndication addresses the needs of enterprises to manage their information assets using content intelligence techniques based on an offer-subscription method.

Syndication of content using OpenDeploy entails the following steps:

Configuring offers around metadata rules. This may involve specifying a metadata query that will yield the appropriate manifest of files to be delivered from a source area.

Creating subscriptions by scheduling distribution jobs that correspond to offers. The jobs would typically deliver updates to specific audiences at certain times or at recurring intervals. Business contract rules and recipient preferences typically dictate the delivery schedule.

(If you are employing a query-based payload adapter) Tagging content with metadata that can be used by distribution jobs for determining which assets to deliver. How content is tagged is determined as part of an organization’s business process. For example, a financial report about a specific mutual fund may be tagged with the attribute fundType=growth.

Transmitting assets to target recipients using a chosen delivery mechanism. This could be either the setting up of an OpenDeploy receiver for accepting transmitted assets, or a delivery adapter-based approach such as using an FTP drop zone or through e-mail. TeamSite users may also want content to be delivered directly into another TeamSite repository for re-purposing.

Syndication requires that the OpenDeploy Intelligent Delivery module be licensed on the base server. Refer to “Add-On Module Licensing” on page 152 in the OpenDeploy Installation Guide for more information.

You can run syndicated deployments using the following methods:

From the browser-based user interface — you can compose offer and subscription configuration files in a manner similar to composing deployment configurations.

From the command-line — you can compose offer and subscription files manually using a text or XML editor, and then process them using command-line tools.

Using Web services — see “Using Web Services” on page 426 for a description of this method.

389

Syndication

How Syndication Works

Syndication consists of the following components:

Offers

Subscriptions, including subscription schedules.

Offers

The syndication process begins with the creation of the offer. An offer includes a user-defined, XML-based configuration file that contains the source file location and the deployment type.

The most common deployment type of an offer is payload adapter-based. Employing this type of deployment requires that your source content is tagged with metadata that can be used by distribution jobs for determining which assets to deliver. How content is tagged is determined as part of an organization’s business process. For example, a financial report about a specific mutual fund may be tagged with the attribute fundType=growth.

You can also employ other deployment types, such as directory comparison or TeamSite comparison, in a syndication offer. These types of deployment require either that the recipient of the syndicated content run OpenDeploy base server or receiver software to accept the deployed content, or the use of a delivery adapter with a base server that can generate a file manifest for deployment to the recipient.

See Chapter 2, “Deployment Types” on page 79 for information on configuration deployment types and their source file locations.

Subscriptions

After an offer is created, you can create a subscription. Creating a subscription results in the following actions:

The subscription is matched to an offer, resulting in a completed deployment configuration that can deploy the syndicated content to its intended recipients.

Links are established between the subscription and its associated offer.

Scheduling information is established for the generated subscription.

A subscription includes a subscription configuration file. The subscription configuration file includes the additional elements and attributes that can complete a deployment configuration in conjunction with the offer.

Like with offers, you can compose the subscription configuration file either in the browser-based user interface, or manually using a text or XML editor.


User Interface

Schedules

Included in the subscription configuration file is scheduling information that specifies the following items:

Start time

Frequency

End time (if necessary)

If you compose your subscription in the browser-based user interface, OpenDeploy assigns a default schedule. However, you can update and change that schedule at any time through the user interface.

If you compose your subscription manually for use with the command-line, you can configure the schedule any way you want. You also have the ability to create a separate subscription configuration file with the updated schedule settings, and update your subscription by running the appropriate command-line tool.

User Interface

This section describes performing syndication tasks using the OpenDeploy browser-based user interface.

Offers

The OpenDeploy browser-based user interface includes an offer composition tool that leads you through the creation steps, and also processes it when you save the file.

To compose an offer using the browser-based user interface, follow these steps:

1. Select Syndication > Offer to display the Offer window (Figure 1).

Figure 1: Offer Window

391

Syndication

2. Select the OpenDeploy server on which you will save the offer from the Selected Server list.

3. Click New to display the Offer window (Figure 2).


The Offer window contains a tree on the left that lists the elements contained in the offer configuration file. Those elements listed in red have yet to be configured. As you assign values to these elements, those values are reflected in the tree.

4. Enter the name of the offer in the Offer Name box.

5. Click Edit to display the Source window (Figure 3).

Figure 3: Source Window

6. (optional) Enter a name for the source element in the Name box.

7. Select one of the following the source file location types from the Source Repository Type list:

fileSystem — source file location is a file system location.

iwStore — source file location is a TeamSite area.


User Interface

8. Select the fileSystem or iwStore entry (depending on which one you selected in the previous step) from the tree. This updates the tree and displays the fileSystem (Figure 4) or iwStore window.

Figure 4: fileSystem Window

9. Select the one of the following deployment type options from the Deploy Type list:

RemoteDiff — directory comparison

FileList — file list deployment

AreaDiff — (iwStore only) TeamSite comparison

PayLoad — payload adapter-based

Beneath the Deploy Type list is a table containing the deployment type entries. The attributes displayed vary with the type of deployment you select. For example, if you selected FileList, the following entry is displayed (Figure 5):

Figure 5: FileList Deployment Type Entry

10. Enter the attribute values for the deployment type entry.

Each deployment type entry has an associated Name attribute. Assign a unique name to each deployment entry you add. In addition, the following attributes are displayed for each deployment type:

RemoteDiff:


FileList:


• File Path — specify the full path to the manifest file.

AreaDiff (iwStore only)

• Area — specify the full path to the source TeamSite area.

• Previous Area — specify the full path to the previous TeamSite area.

393

Syndication

PayLoad

• Area — specify the full path to the source file system location or TeamSite area. There are additional configuration tasks associated with payload deployment types. See “Configuring Payload Deployments” on page 395 before proceeding to the next step.

11. Click the New Source Deployment Type button to add another entry to the table. You can add as many entries as you want, but they must all be of the same deployment type. You cannot include a mix of deployment types in the same offer configuration file.

12. Select the Path Specification element associated with your deployment type entry in the tree. Here you can configure the following additional settings for the associated deployment type entry:

Path

Filter set

Source transfer rules

Target rules

Configuring these settings in your offer configuration file is similar to using the Deployment Configuration Composer to compose an entire deployment configuration. See “Defining a Subdirectory Within the Source File Location” on page 361 for descriptions of these tasks.

13. Repeat this procedure for each Path Specification element present in the tree.

14. Click Save to save the offer configuration file.

The completed offer configuration file is displayed (Figure 6):

Figure 6: Offer Configuration File

Select the Errors tab in the tree to view any errors that might have occurred with your file.

Saving your offer configuration file also processes it in the same manner as running the iwodcmd offeradd command-line tool with a manually-created file. OpenDeploy saves the offer file in the following location:

od-home/conf/iwodoffer


User Interface

Deployment Groups

Use of deployment groups within the iwodoffer directory is not supported when using the browser-based user interface. If you want to place your offers into deployment groups, use the command-line method, described in “Offers” on page 408.

Configuring Payload Deployments

If you select Payload as the deployment type and configured it as specified in step 10 of the previous section, there are additional tasks you must perform, starting in the payLoad element window (Figure 7).

Figure 7: payLoad Element Window

1. Click the payLoadRules Edit button to display the payLoadRules window (Figure 8).

Figure 8: payLoadRules Window

2. Select one of the following options from the PayLoad Rules list:

Customer Defined Rules — indicates a payload adapter is being used that does not support the OpenDeploy query syntax.

Query — indicates an adapter that supports the OpenDeploy query syntax is being used.

See “Providing Input to the Adapter” on page 125 for an overview of these options.

The option you select appears as an element entry in the tree. Select that element to display additional configuration windows. The following sections describe configuring each option.

395

Syndication

Customer Defined Rules

If you are using an adapter that does not support the OpenDeploy query syntax, such as the GenericRetrievalExample adapter or the Intelligent Delivery module’s TQueryGenericRetrieval adapter, or an adapter that you provide yourself, you must construct the query as a CDATA string within the Customer Defined Rules window.

Selecting the Customer Defined Rules element in the tree displays the Customer Defined Rules window (Figure 9).

Figure 9: Customer Defined Rules Window

Here you must enter the constructed query as a CDATA string, for example:

<![CDATA[SELECT path FROM table1 WHERE name='jdoe']]>

See “Using a PCDATA String” on page 125 for more information.


If you are using an adapter that supports the OpenDeploy query syntax, such as the QueryRetrievalExample adapter or the Intelligent Delivery module’s TQueryGenericRetrieval adapter, you can construct the query using the OpenDeploy query syntax.

1. Select the Query element in the tree to display the Query window (Figure 10).

Figure 10: Query Window

Here you can construct your query using the OpenDeploy query syntax. See “OpenDeploy Query Syntax” on page 126 to familiarize yourself before beginning the query construction.


User Interface

2. Select Predicate from the Query Item list to display a Predicate entry in the Query window (Figure 11).

Figure 11: Predicate Entry

3. Enter the operator and value information as described in “OpenDeploy Query Syntax” on page 126.

If you want to include multiple predicate elements linked with the AND or OR element, select And or Or from the Query Item list to display the associated window. Figure 12 shows an AND entry:

Figure 12: And Entry

4. Use of AND or OR requires that you include at least two predicate elements in your query. You cannot includes both AND and OR element in the same query.

5. Click the Edit button associated with a predicate element entry, either in the Predicate window, or in the AND or OR windows, to display the Predicate window (Figure 13).

Figure 13: Predicate Window

Here, the operator and value attributes associated with the predicate element are displayed. In addition, the Key: Edit button is present. Click Edit to display the Key window (Figure 14).

Figure 14: Key Window

397

Syndication

6. Enter the metadata key name in the Key Name box. Select one of the following options from the Query Key Type list:

Text Type — indicates the value is text string.

Numeric Type — indicates the value is numeric.

Date Type — indicates the value is based on a specified date format. Selecting this option causes the Date Type and Date Format items to appear in the Key window (see below:

Date Type — select of the following options:

• date — reflects the day, month, and year; or

• timestamp — reflects the second, minute, hour, day, month, and year.

Date Format — enter the SimpleDateFormat Java class format for the date or timestamp (as specified by the Date Type box attribute), for example:

dd/mm/yyyy (indicates day/month/full year) orss/mm/hh/dd/mm/yyyyy


http://java.sun.com/j2se/1.3/docs/api/java/text/SimpleDateFormat.html

Payload Deployment Actions

When you specify the deployment type as a payload, you must indicate what kind of action OpenDeploy is to take

Select the Action element from the tree to display the Action window (Figure 15).

Figure 15: Action Window

Enter one of the following actions options in the Name box:

deploy — indicates the files in the manifest are compared with the files in the target and, if appropriate, deployed. This is the default value. If no value is specified for the name attribute, OpenDeploy runs the deployment using the default value.

expire — indicates the files in the manifest are removed from the target file location. In this case, no comparison of these files with the target files occurs.



User Interface

Editing an Offer

To edit an offer, follow these steps:

1. Select Syndication > Offer to display the Offer window.

2. Select the OpenDeploy server on that contains the offer from the Selected Server list.

3. Select the offer you want to edit from the Offer list.

4. Click Edit. The Offer control form is displayed containing the elements and attributes for the offer you selected.

5. Edit your offer as necessary using the same methods as described in “Offers” on page 391.

6. Click Save to save the offer.

Deleting an Offer

To delete an offer, follow these steps:

1. Select Syndication > Offer to display the Offer window.

2. Select the OpenDeploy server on that contains the offer from the Selected Server list.

3. Select the offer you want to delete from the Offer list.

4. Click Delete.

399

Syndication

Subscriptions

The OpenDeploy browser-based user interface includes a subscription composition tool that leads you through the creation steps.

To compose an offer using the browser-based user interface, follow these steps:

1. Select Syndication > Subscription to display the Subscription window (Figure 16).

Figure 16: Subscription Window

2. Select the OpenDeploy server on which you will save the subscription from the Selected Server list.

3. Click New to display the Subscription composer window (Figure 2).

Figure 17: Subscription Window

The Subscription composer window contains a tree on the left that lists the elements contained in the subscription configuration file. Those elements listed in red have yet to be configured. As you assign values to these elements, those values are reflected in the tree.

4. Enter the name of the subscription in the Subscription Name box.


User Interface

5. Click Offer: Edit to display the Offer window (Figure 18).


6. Enter the offer with which you want to use with the subscription in the Offer Name box.

7. Select Delivery in the tree to display the Delivery window (Figure 19).

Figure 19: Delivery Window

8. Select one of the following delivery methods from the Delivery Types list:

OpenDeploy — the recipient provides a host running OpenDeploy base server or receiver software capable of receiving the deployed content. This method allows the syndicated deployment of both content files and associated metadata between TeamSite repositories.

ftp Set — syndicated content files are moved to a temporary location on the sending host. From this temporary directory, the OpenDeploy FTP delivery adapter can access the content files and FTP them to the recipient.

email Set — syndicated content files are moved to a temporary location on the sending host. From this temporary directory, the OpenDeploy email delivery adapter can access the content files and email them to the recipient.

The following section describes configuring each delivery method:

401

Syndication

Configuration Delivery Methods

If you selected OpenDeploy from the Delivery Types list, the OpenDeploy window (Figure 20) is displayed:

Figure 20: OpenDeploy Window

The OpenDeploy window contains the following configurable items:

Transactional options — select yes or no to make the deployment transactional.

Log Rules button — click to configure deployment logging.

Local Node button — click to specify the sending host, and to configure encryption.

Replication Farms button — click to specify replication farms, and to specify the quorum value.

Target button — click to specify the target replication farm, the target file location, and other settings associated with targets.

Deploy and Run button — click to assign and configure Deploy and Run scripts to the deployment.

New DNR Deployment Job button — click to add a configurable Deploy and Run deployment job entry, containing the items listed below:

location options — select the target or source option to indicate whether the Deploy and Run is triggered on the target side or the source side.

when options — select the before or after option to indicated whether the Deploy and Run is triggered before or after the deployment is run.

state list — select whether the Deploy and Run is triggered only if the deployment is a success, or failure, or always.

Delete button — click to delete the associated DNR Deployment Job entry.

See “Creating a New Configuration” on page 341 for instructions on how to configure these features and settings.


User Interface

If you selected ftp Set from the Delivery Types list, the ftp Set window (Figure 21) is displayed:

Figure 21: ftp Set Windows

The ftp Set window contains the following configurable items:

ftp Temporary Directory box — click to specify the absolute path to a location on the sending host where the content is temporarily deployed.



Permission Rules button — click to define the rules applicable to the permissions of deployed files and directories


New ftp button — click to add another ftp entry containing the items listed below:

Instance Name box — enter the unique name of the ftp element.

propertyFile box — enter the full path to the FTP properties file on the server host. The FTP properties file is a text file containing the following FTP-based attributes:

• Host — specify the resolvable host name or IP address of the recipient host.

• User — specify the user ID.

• Password — specify the password associated with the user ID.

• TargetDir — specify the target directory for the deployed files.

For example:

Host=mars.mycompany.com

User=jdoe

Password=123abc

TargetDir=/website/files

403

Syndication

You must provide this file in a location on your host where it can be accessed using the path your provide here. For example:

/usr/files/ftpprop1.txt

Delete button — click to delete the associated ftp entry.






See “Creating a New Configuration” on page 341 for instructions on how to configure these features and settings.

If you selected email Set from the Delivery Types list, the email Set window (Figure 22) is displayed:

Figure 22: email Set Window

The email Set window contains the following configurable items:

email Temporary Directory box — click to specify the absolute path to a location on the sending host where the content is temporarily deployed.




New email button — click to add another email entry containing the items listed below:

Instance Name box — enter the unique name of the email element.


User Interface

email Address box — enter the email address of the recipient.

Delete button — click to delete the associated email entry.






Completing the Subscription Configuration File

After you have specified and configured the deployment method, you must complete the rest of the subscription configuration file. This includes specifying the local node, and for OpenDeploy deployment types, replication farms and target file location configuration. See “Creating a New Configuration” on page 341 for information regarding these tasks.

Click Save to create the subscription file when you have completed configuring it. The Subscription windows displays the completed syndicated deployment configuration and the default schedule in the Subscription window (Figure 23).

Figure 23: Subscription Window After Creating Subscription

Saving your subscription configuration file also processes it in the same manner as running the iwodcmd subscriptionadd command-line tool with a manually-created file. OpenDeploy saves the subscription file in the following location:

od-home/conf/iwodsubscr

405

Syndication

Deployment Groups

Use of deployment groups within the iwodsubscr directory is not supported when using the browser-based user interface. If you want to place your subscriptions into deployment groups, use the command-line method, described in “Subscriptions” on page 410.

Deleting a Subscription

To delete a subscription, follow these steps:

1. Select Syndication > Subscription to display the Subscription window.

2. Select the OpenDeploy server on that contains the subscription from the Selected Server list.

3. Select the subscription you want to delete from the Subscription list.

4. Click Delete.

Schedules

The subscription schedule is displayed (Figure 24) in the Subscription window when you create the subscription:

Figure 24: Subscription Schedule

By default, OpenDeploy assigns the following schedule values to a new subscription you created in the user interface:

Start time and date — one hour after the time and date it was created. For example, if you created the subscription at 10:00 a.m. on June1 2004, the start time and date would be 11:00 a.m. on June 1 2004.


User Interface

Changing the Schedule

You can change the schedule of a subscription by clicking the Edit button associated with it to display the Edit Schedule window (Figure 25).

Figure 25: Edit Schedule Window

You configure the schedule for the subscription in the same manner as for a deployment. See Chapter 6, “Scheduled Deployments” on page 235 for a complete description of how to configure schedules.

Suspending Subscriptions

You can suspend the subscription at any time. Suspending the subscription does not delete the subscription file, or its associated links with its offer, or its scheduling information. Instead, it prevents the subscription from deploying syndicated files. You can re-enable a suspended subscription at any time without having to recreate it.

To suspend an active subscription, click the Hold button associated with the subscription. When the subscription is suspended, the Active column displays no, and the Hold button changes to Activate. Click Activate to re-enable a suspended subscription.

Viewing Subscriptions from the Offer

You can view which subscriptions are generated particular offer by selecting Syndication > Offer to display the Offer window, and selecting your offer from the Offer list. The offer code is displayed, and underneath is a list of subscriptions (Figure 26).

Figure 26: Subscriptions from the Offer

407

Syndication

Command-Line

You can configure and process offers and subscriptions using command-line tools and a text or XML editor to compose the offer and subscription configuration files.

Offers

You can create an offer configuration file manually and then process it from the command-line using the iwodcmd offeradd command-line tool. The offer element is the root element of the offer configuration file.

Use your favorite text or XML editor to compose your offer configuration file. The offer configuration file contains the root element offer, and the source element.

<offer><source><iwStore>

<payload area="/default/main/branch1/STAGING"><pathSpecification>

<path name="."/> </pathSpecification><payLoadRules>

<action name="expire"/><query><predicate operator="CONTAIN" value="Title">

<key name="Title"><textType/>

</key></predicate>


</payload></iwStore>

</source></offer>

Within the source element is the same elements and attributes as in other deployment configurations. Within the source element you can specify either a file system location (fileSystem) or a TeamSite area (iwStore). See Chapter 2, “Deployment Types” on page 79 for information on configuration deployment types and their source file locations.

If your offer’s deployment type is payload adapter-based, you must configure either a user-defined query, or one using the OpenDeploy query syntax. See “Payload Adapter-Based Deployments” on page 121 for more information.


Command-Line

Processing the Offer

After the offer configuration file is created, you must process it through OpenDeploy using the iwodcmd offeradd command-line tool.

To process the offer configuration file, follow these steps:


od-home/bin


iwodcmd [-odinst instName] offeradd -o offerName -f offerConfigFile

where offerName is the name of the offer you specify, and offerConfig is the full path to the offer configuration file.

For example, if you wanted to create the offer financial_reports from an offer configuration file residing at the location /usr/local/fncrpts.xml, you would enter:

iwodcmd offeradd -o financial_reports -f /usr/local/fncrpts.xml

After processing the offer configuration file using iwodcmd offeradd, the offer file financial_reports.xml is generated into the following location:

od-home/conf/iwodoffer

All generated offer files must reside within the od-home/conf/iwodoffer location. However, you can specify a subdirectory under iwodoffer by including that subdirectory in your offer configuration file when running iwodcmd offeradd. For example, if you wanted the offer file to reside in the subdirectory reports, you would enter the following command:

iwodcmd offeradd -o reports/financial_reports -f /usr/local/fncrpts.xml

After running the command, the offer resides in the following location:

od-home/conf/iwodoffer/reports/financial_reports.xml

The generated offer file is identical to the offer configuration file. However, processing the offer configuration file using iwodcmd offeradd applies tracking links and other attributes to the offer.

409

Syndication

Subscriptions

After the offer is created, you must create the subscription. Creating a subscription results in the following actions:

The subscription is matched to an offer, resulting in a completed deployment configuration that can deploy the syndicated content to its intended recipients.

Links are established between the subscription and its associated offer.

Scheduling information is established for the generated subscription.

A subscription includes a subscription configuration file. The subscription configuration file includes the additional elements and attributes that can complete a deployment configuration in conjunction with the offer.

Like with offers, you can compose the subscription configuration file either in the browser-based user interface, or manually using a text or XML editor.

Use your favorite text or XML editor to compose your subscription configuration file. The subscription configuration file contains the following components:

Delivery configuration, which includes the deployment method, targets, the target file location, deployment rules, Deploy and Run configurations, and other deployment information.

Scheduling information, including the start time and frequency of the subscription.

The subscription configuration file can reside anywhere on the base server.


Command-Line

The subscription element is the root element. Within the subscription element are the configurations for the delivery method and the schedule.

<subscription><delivery><openDeploy>

<logRules maxBytes="32Mb" level="verbose"/><localNode host="mars"/><replicationFarmSet><replicationFarm name="MYFARMNAME">


</replicationFarmSet><target><targetFilesystem area="/var/tmp/odtest"/><comparisonRules dateDifferent="yes"/><transferRules doDeletes="yes"/><permissionRules file="0644" directory="0755"/><replicationFarmLink>

<internal name="MYFARMNAME"/></replicationFarmLink>

</target></openDeploy>

</delivery><schedule><startTime year="2004" month="02" day="02" hour="12" minute="00"/><description>This is a monthly syndication of finanacial

reports</description><frequency>

<discrete interval="1"><type>

</weekly weekday="wed"></type><endTime year="2004" month="14" day="15" hour="18"

minute="00"/></discrete>

</frequency></schedule>

</subscription>

411

Syndication

Specifying the Delivery Method

The delivery method used to move the content from the sending source to the recipient is defined within the subscription configuration file. OpenDeploy syndication supports the following delivery methods:

OpenDeploy — the recipient provides a host running OpenDeploy base server or receiver software capable of receiving the deployed content. This method allows the syndicated deployment of both content files and associated metadata between TeamSite repositories.

FTP — syndicated content files are moved to a temporary location on the sending host. From this temporary directory, the OpenDeploy FTP delivery adapter can access the content files and FTP them to the recipient.

Email — syndicated content files are moved to a temporary location on the sending host. From this temporary directory, the OpenDeploy email delivery adapter can access the content files and email them to the recipient.

In the subscription configuration file, the delivery method is specified within the delivery element:

<subscription><delivery>...

</delivery>...

</subscription>

The configuration within the delivery element varies depending on the type of delivery method being used.


Command-Line

OpenDeploy

The OpenDeploy delivery method in the subscription configuration file is configured in a similar manner to deployment configurations. Deployment of syndicated content to an OpenDeploy base server or receiver host is configured using the opendeploy element:

<delivery><openDeploy><logRules maxBytes="32Mb" level="verbose"/><localNode host="mars"/><replicationFarmSet>

<replicationFarm name="MYFARMNAME"><nodeRef useNode="MyLocalHost"/>

</replicationFarm></replicationFarmSet><target>

<targetFilesystem area="/var/tmp/odtest"/><comparisonRules dateDifferent="yes"/><transferRules doDeletes="yes"/><permissionRules file="0644" directory="0755"/><replicationFarmLink><internal name="MYFARMNAME"/>


</openDeploy></delivery>

The opendeploy element contains the transactional attribute.

<opendeploy transactional="yes">

If the transactional attribute is specified as yes, then in the event of a deployment error, the deployment is reversed and the target files are restored to their previous state. The default value is no. If the transactional attribute is specified as no, or if the transactional attribute is omitted, the feature is disabled. See “Transactional Deployments” on page 145 for more information on this feature.

Within the opendeploy element are the following child elements:

logRules — see Chapter 7, “Logging” on page 251.

localNode — see “Specifying the Deployment Host” on page 86.

replicationFarmSet — see “Target Replication Farms” on page 89.

target — see “Target File Location” on page 97. Also see Chapter 4, “Deployment Features” on page 175 for information on features configured within the target element.

dnrDeploymentJob — see Chapter 5, “Deploy and Run” on page 215.

deployNRun — see Chapter 5, “Deploy and Run” on page 215.

413

Syndication

FTP

FTP delivery relies on the OpenDeploy FTP delivery adapter to move the syndicated files to the target using the file transfer protocol. FTP delivery is configured within the ftpSet element:

<delivery><ftpSet tmpDir="/usr/tmp/ftp">

<ftp name="ftp1" host="jupiter.mycompany.com" user="jdoe"password="123ABC" targetDir="/pub/ftp/reports"/>

<logRules maxBytes="32Mb" level="verbose"/><localNode host="mars"/><permissionRules file="0644" directory="0755"/>

</ftpSet></delivery>

</delivery>

The ftpSet element contains the tmpDir attribute. The tmpDir attribute specifies the absolute path to a location on the sending server where the content is temporarily deployed. For example:

<ftpSet tmpDir="/usr/tmp/ftp">

After the content is deployed to this temporary location, the OpenDeploy FTP adapter accesses it and moves the content to its target destination using FTP.

Within the ftpSet element are the following child elements:

ftp — see below.



permissionRules — see “Permission Rules” on page 193.



The ftp element contains the following attributes:

name — specify the unique name of the ftp element.

host — specify the resolvable host name or IP address of the recipient host.

user — specify the FTP user name.

password — specify the FTP password.

targetDir — specify the target directory within the FTP site.

parameter — (optional) specify any additional user-defined information as supported by the delivery adapter.

You can include multiple ftp elements in your subscription configuration file, one for each individual FTP-based deployment of the syndicate files.


Command-Line

Email

Email delivery relies on the OpenDeploy email delivery adapter to move the syndicated files to the target as attachments to an email message. Email delivery is configured within the emailSet element:

<delivery><emailSet tmpDir="/usr/tmp/email"><email name="email1" address="[email protected]"/>...

</emailSet></delivery>

The emailSet element contains the tmpDir attribute. The tmpDir attribute specifies the absolute path to a location on the sending host where the content is temporarily deployed. For example:

<emailSet tmpDir="/usr/tmp/email">

After the content is deployed to this temporary location, the OpenDeploy email adapter accesses it and sends the files as an attachment to an email message.

Within the emailSet element are the following child elements:

email — see below.





The email element contains the following attributes:

name — specify the unique name of the email element.

address — specify the email address of the recipient.

parameter — (optional) specify any additional user-defined information as supported by the delivery adapter.

You can include multiple email elements in your subscription configuration file, each one to a different address.

415

Syndication

Specifying the Deployment Schedule

The schedule element is the root element. The schedule element includes the following attributes:

parameters — specify any parameter substitution key=value entries you want to employ in the deployment. See “Parameter Substitution” on page 203 for more information.

instanceName — specify the instance name of the deployment. See “Deployment Instance Naming” on page 58 for more information.

Start Time

Within the schedule element is the startTime element, which specifies when the syndicated deployment associated with the subscription will be run for the first time.

<schedule><startTime year="2004" month="04" day="05" hour="18" minute="00"/>...

</schedule>

The startTime element contains the following attributes:

year — specify the four-digit year value, for example:

year="2004"

month — specify the two-digit month (01-12) value. For example, the month April would be specified as:

month="04"

day — specify the two-digit date of the month (01-31) value. For example:

day="05"

hour — specify the two-digit 24 hour (00-23) value. For example, 6:00 pm would be:

hour="18"

minute — specify the two-digit minute (00-59) value. For example:

minute="00"

For example, a start time of April 5, 2004 at 6:00pm would be configured as:

<startTime year="2004" month="04" day="05" hour="18" minute="00"/>


Command-Line

Frequency

The frequency element specifies how often the syndication of content will occur, based on which child element is configured.

<schedule><startTime year="2004" month="04" day="05" hour="18" minute="00"/><frequency>...

</frequency>...

</schedule>

If you want the deployment to only occur once, include the once element within the frequency element:

<frequency><once/>

</frequency>

If you want the syndicated deployment to occur multiple times, include the discrete element within the frequency element:

<frequency><discrete ...>...

<discrete ...></frequency>

The discrete element’s interval attribute specifies the number of time periods (specified later in this section) between syndicated deployments, for example:

<discrete interval="1">

In this example, the syndicated deployment occurs every single specified time period (such as hours, days, or weeks). If the interval was increased to 2:

<discrete interval="2">

the syndicated deployment occurs every two specified time periods, such as every two hours or two weeks.

The discrete element contains the following child elements:

type — defines the time interval (hour, day, week, and so on) the deployment occurs.

endTime — defines the timeframe when the deployment will no longer occur.

<discrete interval="1"><type>...

</type><endTime ... />

<discrete>

417

Syndication

You must specify one of the following child elements within the type element, depending on the run time interval you want to set for the deployment:

sub-hourly (minutes)hourly

daily

weekly

monthly

The sub-hourly element specifies the time period in minutes. You must specify the number of minutes as the discrete element’s interval attribute value. For example:

<discrete interval="30"><type><sub-hourly/>


<discrete>

In this example, the deployment interval is every 30 minutes.

Use the sub-hourly element if you want to specify syndicated deployment occurring at fractional hourly time periods. For example, you would not be permitted to specify an interval of 1.5 hours. Instead, you would have to specify an interval of 90 minutes.

Configuring the sub-hourly, hourly, and daily elements requires no additional configuration within the type element. For example

<type><hourly/>

</type>

or

<type><daily/>

</type>

However, if you configure the weekly or monthly, you must perform additional configurations.

The weekly element contains the weekday attribute, whose value specifies the day of the week when the deployment occurs, for example:

<type><weekly weekday="wed"/>

</type>


Command-Line

The weekday attribute supports the following values:

mon — Monday

tue — Tuesday

wed — Wednesday

thu — Thursday

fri — Friday

sat — Saturday

sun — Sunday

The monthly element contains the monthDays attribute, whose value specifies the dates during the month when the deployment occurs. The value must be from 1 to 31. Separate multiple dates with a comma (“,”). For example:

<type><montyly monthDays="1,15"/>

</type>

End Time

If you are scheduling recurring scheduled syndication deployments, you must specify an end time when the recurring deployments will no longer occur. The end time is specified by the endTime element.

<discrete interval="1"><type>...


<discrete>

Inclusion of the endTime element is only necessary if multiple syndicated deployments are being configuration (indicated by the presence of the discrete element).

The endTime element contains the following attributes:

year — specify the four-digit year value, for example:

year="2004"

month — specify the two-digit month (01-12) value. For example, the month December would be specified as:

month="12"

day — specify the two-digit date of the month (01-31) value. For example:

day="31"

hour — specify the two-digit 24 hour (00-23) value. For example, 6:00 pm would be:

hour="23"

419

Syndication

minute — specify the two-digit minute (00-59) value. For example:minute="59"

For example, an end time of December 31, 2004 at 11:59pm would be configured as:

<endTime year="2004" month="12" day="31" hour="23" minute="59"/>

Processing the Subscription

After the subscription configuration file is created, you must process it through OpenDeploy using the iwodcmd subscriptionadd command-line tool.

To process the subscription configuration file, follow these steps:


od-home/bin


iwodcmd [-odinst instName] subscriptionadd -o offerName -s subscriptionName -f subscriptionConfigFile

where offerName is the name of the offer you specify, and subscriptionConfigFile is the full path to the subscription configuration file.

For example, if you wanted to create the subscription Q105_prospectus using the offer financial_reports and the subscription configuration file residing at the location /usr/local/prospectus.xml, you would enter:

iwodcmd subscriptionadd -o financial_reports -s Q105_prospectus -f /usr/local/prospectus.xml

After processing the subscription configuration file using iwodcmd subscriptionadd, the subscription file financial_reports.xml is generated into the following location:

od-home/conf/iwodsubscr

All generated subscription files must reside within the od-home/conf/iwodsubscr location. However, you can specify a subdirectory under iwodsubscr by including that subdirectory in your offer configuration file when running iwodcmd subscriptionadd. For example, if you wanted the subscription file to reside in the subdirectory prospectus, you would enter the following command:

iwodcmd subscriptionadd -o financial_reports -s prospectus/Q105_prospectus -f /usr/local/prospectus.xml

After running the command, the subscription resides in the following location:

od-home/conf/iwodsubscr/prospectus/Q105_prospectus.xml


Command-Line

When the subscription configuration file is processed using iwodcmd subscriptionadd, the configuration in the subscription configuration file is combined with that of the associated offer file to create a valid deployment configuration. For example:

<deploymentConfiguration><logRules level="verbose" maxBytes="32Mb"/><localNode host="mars"/><replicationFarmSet><replicationFarm name="MYFARMNAME">


</replicationFarmSet><definition name="MYDEFINITIONNAME"><source>

<iwStore><payload area="/default/main/branch1/STAGING">


</pathSpecification><payLoadRules><action name="expire"/>

<query><predicate operator="CONTAIN" value="Title"><key name="Title"><textType/>

</key></predicate>


</payload></iwStore>

</source><target>

<targetFilesystem area="/var/tmp/odtest"/><comparisonRules dateDifferent="yes"/><transferRules doDeletes="yes"/><permissionRules directory="0755" file="0644"/><replicationFarmLink><internal name="MYFARMNAME"/>


</definition><deployment transactional=""><execDeploymentTask useDefinition="MYDEFINITIONNAME"/>

</deployment></deploymentConfiguration>

421

Syndication

Displaying Offers and Subscriptions

You can display the contents of offer and subscription files using the iwodcmd offerget and iwodcmd subscriptionget command-line tools, respectively. Using these tools allows you to view the configuration of the files. Additionally, you can use these tools to retrieve the content for use as the basis of other offers and subscriptions.

Offers

The access an offer file, follow these steps:


od-home/bin


iwodcmd [-odinst instName] offerget -o offerName

where offerName is the name of the offer you specify.

If the offer resides in a subdirectory, include the subdirectory name in front of the offer name.

The contents of the offer file you specified are displayed.

Subscriptions

To access a subscription file, follow these steps:


od-home/bin


iwodcmd [-odinst instName] subscriptionget -o subscriptionName or

where subscriptionName is the name of the subscription you specify.

If the subscription resides in a subdirectory, include the subdirectory name in front of the offer name.

The contents of the subscription file you specified are displayed.


Command-Line

Deleting Offers and Subscriptions

You can delete offers and subscriptions using the iwodcmd offerdelete and iwodcmd subscriptiondelete command-line tools, respectively.

Offers

Deleting an offer removes the offer file from the od-home/conf/iwodoffer directory. In addition, any links between the offer and associated subscriptions are lost.

To delete an offer, follow these steps:


od-home/bin


iwodcmd [-odinst instName] offerdelete -o offerName

where offerName is the name of the offer you specify.

If the offer resides in a subdirectory, include the subdirectory name in front of the offer name.

Subscriptions

Deleting a subscription removes the subscription file from the od-home/conf/iwodsubscr directory. In addition, any links between the subscription and its associated offer are lost, as is all scheduling information for that subscription.

To delete a subscription, follow these steps:


od-home/bin


iwodcmd [-odinst instName] subscriptiondelete -s subscriptionName


If the subscription resides in a subdirectory, include the subdirectory name in front of the subscription name.

Suspending Subscriptions

You can suspend a subscription as an alternative to deleting it using the iwodcmd subscriptionsuspend command-line tool. Suspending the subscription does not delete the subscription file, or its associated links with its offer, or its scheduling information. Instead, it prevents the subscription from deploying syndicated files. You can re-enable a suspended subscription at any time without having to recreate it.

423

Syndication

To suspend a subscription, follow these steps:


od-home/bin


iwodcmd [-odinst instName] subscriptionsuspend -s subscriptionName



Activating Suspended Subscriptions

You can activate a suspended subscription using the iwodcmd subscriptionactivate command-line tool. Activating a suspended subscription returns the subscription to full operability.

To activate a suspended subscription, follow these steps:


od-home/bin


iwodcmd [-odinst instName] subscriptionactivate -s subscriptionName




Command-Line

Schedule Modifications

You can change the schedule associated with a subscription by creating a schedule configuration file containing the updated schedule, and updating the subscription with it using the iwodcmd subscriptionschedupdate command-line tool.

The schedule configuration file is a user-defined, XML-based file:

<schedule><startTime year="2004" month="02" day="02" hour="12" minute="00"/><description>This is a one-time syndication of finanacial reports.

</description><frequency><once/>

</frequency></schedule>

The structure of this file is the same as the scheduling portion of the subscription configuration file. See “Specifying the Deployment Schedule” on page 416 for more information.

Updating the Schedule

To update a subscription’s schedule, follow these steps:


od-home/bin


iwodcmd [-odinst instName] subscriptionschedupdate -s subscriptionName -f schedConfigFile

where subscriptionName is the name of the subscription you specify, and is the full path to the schedule configuration file.

For example, if you wanted to update the schedule for the subscription Q105_prospectus with the settings in the schedule configuration file /usr/local/schedupdate.xml, then you enter:

subscriptionschedupdate -s Q105_prospectus -f /usr/local/schedupdate.xml

425

Syndication

Using Web Services

You can creates offers and make them available to subscribers through a Web-based portal or extranet site by writing an application that calls the OpenDeploy Web services API to present a list of offers. Your subscribers can then select an offer, and then fill in relevant subscription details such as delivery method and frequency. Next, your application calls the Web services API to schedule the syndicated offer for delivery at the chosen time and place. This allows you to present offers to subscribers without having to grant access to the OpenDeploy user interface or having to manually enter subscriptions.

See Chapter 12, “Web Services” on page 427 for an overview of using Web services with OpenDeploy. It is recommended that you familiarize yourself with the syndication functionality described in this chapter before attempting to use syndication with Web services.


Chapter 12

Web Services

ContentServices for OpenDeploy is a SOAP-based interface that allows programmatic access to OpenDeploy functions. The expanded openness afforded through ContentServices for OpenDeploy enables incorporation of content distribution into a Service-Oriented Architecture (SOA). The language-neutral, firewall-friendly programming interface exposes web services using industry-standard WSDL.

Figure 1 shows how ContentServices for OpenDeploy is structured.

Figure 1: ContentServices for OpenDeploy Structure

Using ContentServices for OpenDeploy, you can perform tasks such as the following:

Start a deployment.

Manage deployment schedules.

Obtain status on deployments.

Reset OpenDeploy base server or receivers, and access the status on these servers.

Perform offer-subscription syndication management when used with the optional Intelligent Delivery module.

Client Application

WSDL

SOAP Listener

Web services API


427

Web Services

Using Web Services

ContentServices are Web services from Interwoven that enable integration of functionality from core Interwoven products into line of business applications, such as portals, CRM systems, custom user interfaces, and so on. Programming interfaces are exposed using industry standard WSDL, thereby affording developers the freedom to choose the client programming language (Java, C#, and others) that is most appropriate for a particular application.

Interwoven provides the necessary WSDL layer with its products that support ContentServices. When the WSDL is processed with an appropriate user-defined tool, language-specific bindings are created that allow the client application to communicate its requests to OpenDeploy and other supported Interwoven products. Refer to the ContentServices Foundation documentation for a general overview of how Interwoven Web services work.

Web services support is an integral part of the OpenDeploy base server and receiver product. No additional software is required to be obtained or installed to use Web services.

Figure 2 shows how ContentServices for OpenDeploy works in the context of starting a deployment.

Figure 2: Starting a Deployment Using Web Services

The user-developed client application initiates an authorization request to the ContentServices Foundation access service. The access service processes the request, and returns its response to the client application. After approval of the authentication, the client application initiates a request to start a deployment to the base server through its Web services interface. The user and role associated with the request are checked to ensure the client application is authorized to start the requested deployment. After approval of this check, the deployment can start. All this communication occurs over the SOAP protocol. Use this example of starting a deployment with Web services as a guide when creating and configuring your client application to use OpenDeploy in this manner.

ClientApplication

Access Service Base Server

ContentServices Foundation

ContentServices for OpenDeploy

1. Collect user credentials2. Request authentication

3. Authenticate user and return object.

5. Validate user object and check authorization rule.

4. Request start deployment.

6. Start deployment

SOAP SOAP


OpenDeploy Server Configuration

Web services are available on an OpenDeploy instance basis. Each separate OpenDeploy base server or receiver instance supplies Web services independently from any other instance on the same host.

Each OpenDeploy server instance must be enabled and configured to run Web services in its associated base server or receiver configuration file. Refer to “Web Services” on page 140 in the OpenDeploy Installation Guide for more information on configuring the OpenDeploy server to run Web services.

Access Server Management

Using Web services with OpenDeploy requires that each OpenDeploy base server and receiver has the appropriate ContentServices Foundation access service key file installed. Client applications cannot work with OpenDeploy servers without this required key file. Refer to “Access Service Management” on page 73 in the OpenDeploy Installation Guide for more information.

Tools and Examples

OpenDeploy provides a variety of tools and examples to assist you in using Web services. These items reside in the following location:

od-home/websvc

This directory also includes the file README_OD_WEB_SERVICE, which contains information on how to use the examples.

429

Web Services


Chapter 13

Archival Module

You can archive deployed files to the file system or a storage device using the OpenDeploy Archival module. The Archival module is an optional add-on module to OpenDeploy that archives assets to immutable storage such as write-once, read-many (WORM) devices. It can be used either with ControlHub to archive ControlHub assets (editions) or alone with OpenDeploy to archive file assets. Editions to archive can be specified through an archival policy. Alternatively, specific editions can be selected and archived on an on-demand basis. ControlHub 2.0 does not support the Archival module.

The Archival module enables permanent retention of assets such as records that represent the state of an application in a production environment. Record retention is an important factor in fulfilling regulatory requirements for audit control and compliance. You can also use the Archival module to back-up files or the editions in the ControlHub content store.

The Archival module includes an OpenDeploy connector to the Sun Content Infrastructure System (SunCIS) WORM device. In addition, if the ControlHub module is installed, the Archival module provides the following components:

User interface (UI) plug-in — the UI plug-in enables ControlHub administrators to define archival policies on application branches in the content store. Policies include specifying when to archive and/or delete editions from a branch.

Archival workflow — policies are executed in ControlHub through an archival workflow. The workflow job is configured automatically after you define the archival policies, scheduled for a later time, and can be started on-demand from the ControlHub user interface. The workflow invokes OpenDeploy to perform the archival to the file system or storage device.

Archiving with Standalone OpenDeploy

You can archive files on a standalone OpenDeploy server using the SunCIS delivery adapter. Archiving files in this manner does not require you to install the Archival module, but your OpenDeploy server must still have the Archival module license.

See “SunCIS” on page 470 for more information on configuring the SunCIS delivery adapter.

431

Archival Module

Archiving with ControlHub

This section describes using OpenDeploy with the Archival module in conjunction with ControlHub.

Installation

Use of the Archival module with ControlHub requires that the Archival module software be installed on your OpenDeploy server. Refer to “Archival Module” on page 63 in the OpenDeploy Installation Guide for more information.

Configuring Archival with ControlHub

This section assumes that you are familiar with ControlHub, including how to access its user interface. Refer to the ControlHub Administration Guide for more information on using ControlHub.

A typical archival process using ControlHub consists of the following steps:

Set up the OpenDeploy configuration file to specify the target deployment area.

Navigate to the desired branch to archive.

Define the archival policy for the branch which specifies the editions to archive or delete.

Save the policy.

Click the Start button to start the archival process immediately.

Schedule archives to run in the future on the date and time, and at the frequency, specified.

The archival process invokes OpenDeploy deployment via workflow job to archive specified editions to the file system or WORM device. After a successful archival, editions are deleted if specified in archival policy. You can check the status of archival workflow jobs in the Workflow tab of the ControlHub user interface.

When using the Archival module with OpenDeploy, you must configure your deployment configuration’s target file location to specify where on the device the deployed files are to be written. The deployment configuration fs_archival.xml is provided for use with the Archival module. This file is resides in the following location:

od-home/conf



The fs_archival.xml file is the default deployment configuration file for use with the Archival module in your ControlHub branches. When the Archival workflow is run, it looks for this particular file in its default location. If you want to use another deployment configuration, you must modify the wft_opendeploy.cfg file to specify that alternate file for that branch. The wft_opendeploy.cfg file resides in the following location on ControlHub:

iw-home/local/config/wft/solutions

Open this file using your favorite text editor. Copy the following line:

branchName=/,deployState=archival,deployName=fs_archival

and paste the copy directly before the original line. Then edit the copied line so that the branch name value corresponds to the associated deployment configuration file. For example:

branchName=/default/main/,deployState=archival,deployName=alt_archival

The original line underneath the one you edited provides a default archival deployment for any branches that have not yet been configured.

Refer to “ControlHub Configuration” on page 53 in the ControlHub Administration Guide for more information on the wft_opendeploy.cfg file.

By default, the fs_archval deployment configuration deploys to the following target file location on the sending OpenDeploy server’s host:

od-home/tmp

This target location is intended for testing. You must edit the configuration and substitute your own target file locations for the default one. Note the use of the following parameters in the fs_archival deployment configuration:

<remoteDiff area="$area^"> and

<targetFilesystem area="C:\Interwoven\CPS\OpenDeployNG\tmp\$areavpath^"/>

The $area and $areavpath parameters are filled in by the archival workflow when the workflow job is instantiated. These parameters have the following values:

$area — specifies where the ControlHub editions are located.

$areavpath — specifies the directory under od-home/tmp where the editions are archived.

These parameters are important and ensure that the proper editions are archived and that each branch is archived to a unique location.

433

Archival Module

Defining an Archival Policy

An archival policy specifies for a particular branch which set of editions for that branch to archive. You can also delete editions from the ControlHub content store post-archive. ControlHub saves the policy for the branch and can execute it through an archival workflow job immediately or in the future.

To specify an archival policy for a particular branch, follow these steps:

1. Select the branch to which you want to define the archive policies in the Content tab of the ControlHub user interface.

2. Click the Archive link (or select File > Archive) to display the Branch Archive window (Figure 1).

Figure 1: Branch Archive Window

3. Check the box next to Archive Editions in Branch and select one of the following options:

Archive all editions that have not already been archived.

Archive editions older than the user-specified number of days, weeks, months, or years.

Archive the user-specified number of oldest editions not already archived.

4. Check the box next to Delete Editions from Branch and select one of the following options:

Delete all editions from the branch after they are successfully archived.

Delete editions older than the user-specified number of days, weeks, months, or years.

Retain the user-specified number of most recent editions, and delete all the others.



This window also contains attributes for scheduling the running of the archiving policies you defined. This process is described in “Scheduling Archives” on page 436.

5. Click Save if you want the settings you entered to be the default settings whenever you run the Archive command for that branch.

After you click Save, the Archive window reverts back to the Branches window. Click the Archive link again to display the Branch Archive window if you want to run the archive policies you set.

6. Click Start. A workflow job will commence that executes the policy. A message similar to Figure 2 is displayed showing what archiving and edition deletion activities are pend-ing.

Figure 2: Archive Status Window

7. Click Close to return to the Branches window.

You can change and save your archival policy settings at any time. You can also change your policy settings and run them without saving them. The next time you run open the Branch Archive window, the last saved settings are the ones displayed.

Select Editions and Archive

As an alternative to archiving based on defined archival policies, you can select and archive specific editions. Any archival policy that you may have previously configured for the branch is still preserved. However, you may receive an error if there is an archival workflow in progress when you attempt to select and archive an edition on the same branch.

435

Archival Module

To archive one or more specific editions, follow these steps:

1. Select the editions you want archive in the Editions window (Figure 3)

Figure 3: Editions Window

2. Click the Archive link. A message similar to Figure 4 is displayed showing what archiving and edition deletion activities are pending.

Figure 4: On-demand Archive Status Window

The proposed archiving tasks are displayed. As an option, you can check the box associated with any edition deletion policies to enable those tasks as well.

3. Click Start to begin the archival.

Scheduling Archives

You can schedule a time for an archive to be performed using the scheduling attributes contained in the Branch Archive window where you defined your archival policy(Figure 5).

Figure 5: Archive Scheduling Attributes

To schedule an archive, follow these steps

1. Check the box to indicate you want the scheduled archive to be run.


Running Archival Module Tasks from the Command Line

2. Click the Archive link (or select File > Archive) to display the Branch Archive win-dow.

3. Specify the date and time you want to start your first scheduled archive.

4. Specify the frequency (once, daily, weekly, monthly) that the scheduled archive should occur.

5. Click Save.

If enabled, the schedule archive will run at the time and date specified, and at the frequency you indicated. The scheduled archive is run regardless of whether any archives were also run manually.

Running Archival Module Tasks from the Command Line

You can run certain Archival module tasks from the command-line using the iwodcmd archive command. There are various options associated with the iwodcmd archive command-line tool. Here is a listing of these options, along with the usage syntax:

archive [-h | -v]

archive -l

archive [-b branchVPath] [-r branchVPath] [-lae branchVPath]



-l Gets archival policies for all branches.

-b branchVPath Gets archival policy for a specified branch.

-r branchVPath Starts archival run for a specified branch.

-lae branchVPath Gets list of archived editions for a specified branch.

For example, to get the archival policy for /default/main/, you would enter the following command at the prompt:

iwodcmd archive -b /default/main/

437

Archival Module


Appendix A

Delivery Adapters

This appendix lists and describes the delivery adapters that have been tested and approved for use with OpenDeploy as part of the Delivery Adapter Framework. Currently the following delivery adapters are supported:

Generic delivery

FTP

Email

Network Appliance NetCache

BEA WebLogic 8 Application Server

BEA WebLogic 9 Application Server

IBM WebSphere Application and Portal Servers

BEA bulk loader

Microsoft (included with OpenDeploy on Windows only):

Application Center

COM+

Global Assembly Cache (GAC) Provisioning

Sun Content Infrastructure System (SunCIS)

See “Utilizing the Delivery Adapter Framework” on page 208 for information on how delivery adapters are used.

Note: Use of delivery adapters with EasyDeploy is not supported.

Generic Delivery Adapter

OpenDeploy includes a generic delivery adapter capable of invoking external programs on deployment or rollback. For example, scripts that apply and roll back database configuration changes can be deployed to a target server and then automatically executed by the generic delivery adapter at the appropriate times.

439

Delivery Adapters

Adapter Configuration

The generic delivery adapter requires the presence of an associated XML-based configuration file. This configuration file contains the settings to run the generic delivery adapter.

The generic delivery adapter configuration file can reside anywhere on the target host. You must specify the full path to this file in the deployment configuration file, which is explained in the following section.

The following is an example of this configuration file:

<genericAdapter><deploy cmd="c:\Interwoven\OpenDeployNG\your_deploy_script"/><rollback cmd="c:\Interwoven\OpenDeployNG\your_rollback_script"/>

</genericAdapter>

A sample configuration file (GenericAdapter_example.xml) is included in the following location:

od-home/adapters/delivery/genericAdapter/conf

The generic delivery adapter configuration file contains the container element genericAdapter. Within genericAdapter are the following child elements:

deploy — defines a deployment task.

rollback — defines a rollback task.

Both of these elements contains an associated cmd attribute. Specify the full path to the deploy or rollback script for this attribute value, depending on the element. For example:

<deploy cmd="od-home/bin/iwodstart.sh deploy_script"/>

If your scripts are going to process the manifest of files, they need to be able to accept the manifest file name as an input argument.The script being run must also reside on the target host.


The generic delivery adapter is included in the deployment configuration file using the odAdapter element. See “Configuring Delivery Adapters” on page 210 for a description of the odAdapter element and its attributes.

To configure your deployment to use the generic delivery adapter, follow these steps:

1. Open the deployment configuration file using your favorite text or XML editor. You can also use the OpenDeploy Deployment Configuration Composer for this task.


FTP Adapter

2. Add the following elements and attributes within the target element:<odAdapterSet>

<odAdapter name="GenericAdapter" class="com.interwoven.od.adapter.delivery.genericAdapter.GenericAdapter"parameter="GenDelivConfig_path"/>

</odAdapterSet>

where GenDelivConfig_path is the full path to the generic delivery adapter configuration file.

FTP Adapter

The OpenDeploy FTP adapter allows the delivery of content to a target using file transfer protocol (FTP) in either active or passive mode. Using the FTP adapter does not require having base server or receiver software on the target. The FTP adapter has a configuration file that includes information on the recipient host, user, and the target file location. You must also configure the deployment configuration to reference the FTP adapter. The following sections describe the different components associated with the FTP adapter.


The FTP adapter requires the presence of an associated configuration file. This configuration file contains the settings to run the FTP adapter.

The FTP adapter configuration file can reside anywhere on the target host. You must specify the full path to this file in the deployment configuration file, which is explained in the following section.

The FTP adapter configuration file contains the following attributes:

Host — specify the resolvable host name or IP address of the recipient host.

Port — (optional) specify the FTP server port. This value is needed only if the server is not listening on the default port (21).

User — specify the user ID.

Password — specify the password associated with the user ID.

TargetDir — specify the target directory for the deployed files.

ConnectionMode — (optional) specify the connection mode for the FTP adapter. If you specify the value passive, the adapter uses the “passive” mode of FTP. In passive mode, the adapter opens the data connection to the FTP server. The default value is active, where the adapter uses the “active” mode of FTP. In active mode, the FTP server opens the data connection to the adapter.

441

Delivery Adapters

For example:

Host=mars.mycompany.comPort=21021User=jdoePassword=123abcTargetDir=/website/filesConnectionMode=passive

This file is referenced in the deployment configuration when the FTP adapter is used.

A sample FTP adapter configuration file (ftpconfig.readme) resides in the following location:

od-home/adapters/delivery/ftpadapter


The FTP adapter is included in the deployment configuration file using the odAdapter element. See “Configuring Delivery Adapters” on page 210 for a description of the odAdapter element and its attributes.

To configure your OpenDeploy server to use the FTP adapter, follow these steps:

1. Open the deployment configuration file using your favorite text or XML editor.

2. Add the following elements and attributes within the target element:

<odAdapterSet><odAdapter name="ftp" class="com.interwoven.od.adapter.delivery.ftpadapter.IWftpAdapter" parameter="ftpconfig_path"/>

</odAdapterSet>

where ftpconfig_path is the full path to the FTP adapter configuration file you created in the previous section.

Email Adapter

The OpenDeploy email adapter allows the delivery of content to the recipients as an email attachment. The deployed files are archived together as a .zip file and attached to the email message, which is then sent to the specified recipients.

The email adapter has a configuration file that includes the email address of the recipient, the sender, the email server name, and a subject heading for the email message. You must also configure the deployment configuration to reference the email adapter. The following sections describe the different components associated with the email adapter.


Email Adapter


The email adapter requires the presence of an associated configuration file. This configuration file contains the settings to run the email adapter.

The email adapter configuration file can reside anywhere on the target host. You must specify the full path to this file in the deployment configuration file, which is explained in the following section.

The email adapter configuration file contains the following attributes:

To — specify the email address of the recipient. You can include multiple email addresses. Separate each one with a comma (“,”) or a semi-colon (“;”).

From — specify the email address of the sender.

Host — specify the sender’s mail server host name.

Subject — specify the subject heading of the email.

For example:

[email protected],[email protected][email protected]=mail.mycompany.comSubject=Your deployed files

This file is referenced in the deployment configuration when the email adapter is used.

A sample email adapter configuration file (emailconfig.readme) resides in the following location:

od-home/adapters/delivery/email


The email adapter is included in the deployment configuration file using the odAdapter element. See “Configuring Delivery Adapters” on page 210 for a description of the odAdapter element and its attributes.

To configure your OpenDeploy server to use the email adapter, follow these steps:

1. Open the deployment configuration file using your favorite text or XML editor.


<odAdapter name="email" class="com.interwoven.od.adapter.delivery.email.IWEmailAdapter"parameter=emailconfig_path"/>

</odAdapterSet>

where emailconfig_path is the full path to the email adapter configuration file you created in the previous section.

443

Delivery Adapters

Network Appliance NetCache Adapter

OpenDeploy includes a Network Appliance NetCache adapter that can be integrated into the Delivery Adapter Framework. When configured to use this adapter, an OpenDeploy server can receive deployed content and push this content to the NetCache devices over HTTP. No OpenDeploy software is needed on the NetCache devices.

Figure 1 shows how content is moved from the development source host to the edge servers.

Figure 1: Deploying Content to Edge Servers

Using this method, you can implement a single, consistent, and global solution for distributing content from development to production, and on to the very edge of the network.

OpenDeploy provides the files necessary to configure and run this type of deployment. These files reside in the following location:

od-home/adapters/delivery/netcache/conf

source host target host/origin server for

NetCache devices

edge server

edge server

edge server

content redeployed to edge servers using HTTP

content deployed from source to target




The NetCache adapter requires the presence of an associated XML-based configuration file. This configuration file contains the settings to run the NetCache adapter.

The NetCache adapter configuration file can reside anywhere on the target host. You must specify the full path to this file in the deployment configuration file, which is explained in the following section.


<netCacheServerConfiguration><serverSet><server host="andromeda"

port="3132" userid="jdoe" password="aBcDeF321"isPasswordEncrypted="yes" webServerName="NYweb1"logFile="/dir/logfile.txt"><cacheProperties minAge="60" maxAge="36000" lockTimeout="60"/>

</server></serverSet>

</netCacheServerConfiguration>

A sample NetCache adapter configuration file (NetCache.xml) resides in the following location:

od-home/adapters/netcache/conf

The NetCache adapter configuration file contains a root-level netCacheServerConfiguration element that contains the elements and attributes that determine how deployed content will be pushed to the NetCache edge servers. Within the root element is the serverSet element, which is a container for the individual NetCache server configurations.

Each individual NetCache device is configured by the server element within the serverSet element. There must be a separate occurrence of the server element for each NetCache device to which deployed content is to be pushed. Within the server element, you must specify values for the following attributes:

host — specify the NetCache host name or IP address.

userid — specify the user ID for accessing the NetCache device.

password — specify the password associated with the user ID.

isPasswordEncrypted — indicate whether (yes) or not (no) the password is encrypted using B64 encoding. The default value is no.

webServerName — specify the name of the Web server that acts as the origin server for the NetCache device.

logFile — specify the path and file name of the log file for the adapter.

port — specify the NetCache administration port.

445

Delivery Adapters

With each server element, you have the option of specifying a cacheProperties element and some or all of its associated attributes. The cacheProperties element defines the properties associated with the NetCache server’s cache. Here are the attributes that you can specify within the cacheProperties element:

minAge — (optional) specify the number of seconds that the object in the cache is not visible to HTTP clients.

maxAge — (optional) specify the number of seconds that the object in the cache is valid to HTTP clients.

lockTimeout — (optional) specify the number of seconds that the object in the cache is locked in the cache.


In your OpenDeploy deployment configuration, you must add the following odAdapterSet and odAdapter elements within your target element:

<odAdapterSet><odAdapter name="NetCache"class="com.interwoven.od.adapter.delivery.netcache.IWODNetCache" parameter="NetCacheConfig_path"/>

</odAdapterSet>

where NetCacheConfig_path is the full path to the NetCache adapter configuration file you created in the previous section.

Retrying When Push Fails But Overall Deployment Succeeds

In some cases, the pushing of content to edge serves can fail even if the rest of the deployment succeeded. If this occurs, you can retry the pushing of content to the edge servers without having to rerun the deployment by running the iwodnetcache command line tool.

There are various options associated with the iwodnetcache command-line tool. Here is a listing of these options, along with the usage syntax:

iwodnetcache -h | -v

iwodnetcache -m manifest_file -p config_file -s source_area -d od_home



-m manifest_file Specifies the absolute path to the manifest file. If a full path is not specified, the default directory is od-home/(od-instance)/log.

-p config_file Specifies the absolute path to the NetCache configuration file.



-s source_area Specifies the content source area for the deployment to the NetCache edge servers.

-d od_home Specifies the OpenDeploy home directory (od-home).

For example, if you entered the following command:

iwodnetcache -m rcv.deploy.DEF1.source.to.target.log.mf -p /usr/local/OpenDeployNG/NetCache.xml -s /usr/webfiles -d /usr/local/OpenDeployNG

The path to the manifest file would be:

od-home/log/rcv.deploy.DEF1.source.to.target.log.mf

The path to the NetCache configuration file would be:

/usr/local/OpenDeployNG/NetCache.xml

The content source area location for the content being deployed to the NetCache edge servers would be:

/usr/webfiles

The OpenDeploy home directory is:

/usr/local/OpenDeployNG

Internationalization

NetCache does not support internationalization. As a result, the OpenDeploy NetCache Adapter does not support internationalization.

447

Delivery Adapters

BEA WebLogic 8 Adapter

OpenDeploy includes a delivery adapter that supports application provisioning in archive or exploded format to BEA Systems WebLogic 8 application servers.


The WebLogic 8 adapter requires the presence of an associated XML-based configuration file. This configuration file contains the settings to run the WebLogic 8 adapter.

The WebLogic 8 configuration file can reside anywhere on the target host. You must specify the full path to this file in the deployment configuration file, which is explained in the following section.


<!DOCTYPE weblogic SYSTEM "file:///od-home/adapters/delivery/appserver/weblogic/dtd/WebLogicAppServer.dtd">

<weblogic><admin userName="weblogic" password="weblogic" passwordEncoded="no" weblogicJar="C:\bea81\weblogic81\server\lib\weblogic.jar" explodedFormat="no" adminurl="t3://localhost:7001"/>

<action name="deploy" sourceAccessibility="no" stage="yes" appName="exampleServerName" targets="examplesServer"/>

</weblogic>

A sample configuration file (WebLogicAppServer8Cfg_example.xml) is included in the following location:

od-home/adapters/delivery/appserver/weblogic/conf

You must update the DOCTYPE to include the full path to the WebLogicAppServer.dtd on your host using the following syntax:

<!DOCTYPE weblogic SYSTEM "file:///od-home/adapters/delivery/appserver/weblogic/dtd/WebLogicAppServer.dtd

Note the use of three slashes (“///”).

The WebLogic 8 configuration file contains the container element weblogic. Within weblogic are the following child elements:

admin

action



The admin element contains the following attributes for configuring administrative information:

userName — specify the user name used to connect to the WebLogic administration console.

password — specify the administrative password.

passwordEncoded— indicate whether (yes) or not (no) the password is encrypted. Use the iwodpasscoder OpenDeploy command-line tool to generate the encoded password. Refer to “iwodpasscoder” on page 40 in the OpenDeploy Reference for more information on this tool. Default value is no.

weblogicJar — specify the full path to the .jar file required to run the weblogic.Deployer tool.

explodedFormat — indicate whether (yes) or not (no) exploded format is being used. An exploded archive directory contains the same files and directories as a .jar file archive. However, the files and directories reside directly in your file system and are not packaged into a single archive file with the .jar utility. Refer to your WebLogic documentation for more information. Default value is no.

adminurl — specify the URL of the WebLogic administrative server.

userconfigfile — specify the location of a configuration file to use for obtaining the administative username and password. This attribute is not compatible with the password and excryption attributes.

userkeyfile — specify the location of a user key file to use for encrypting and decrypting (using BEA encryption tools) the username and pasword information stored in the useconfigfile. This attribute is not compatible with the password and excryption attributes.

The action element contains the following attributes for configuring deployment activities:

name — indicate one of the following values:

deploy — deploys an application.

redeploy — replaces a running application or part of a running application.

undeploy — uninstalls a deployed archive from the target server when the archive has been deleted.

You must specify one of the values. There is no default value.

sourceAccessibility — indicates whether (yes) or not (no) the OpenDeploy target directory (the location of the archive file or exploded archive directory to deploy) is accessible to all the target servers. Default value is no.

appName — specify the name of the application.

targets — specify each target server receiving the deployment. Each target server is seperated by a comma (“,”), for example:

targets="target1,target2,target3"

449

Delivery Adapters

stage — indicate whether (yes) or not (no) the deployment uses stage deployment mode. Stage deployments copy deployment files to target servers' staging directories. This is the default mode used when deploying or distributing to Managed Server targets Stage is the default when deploying to managed server targets.Default value is yes.

nostage — indicate whether (yes) or not (no) the deployment uses nostage deployment mode (deployments where there is no staging directory). You cannot configure both stage and nostage in the same deployment configuration. Nostage is the default when deploying to the administration server (for example, in a single-server domain). Default value is yes.

altwlsappdd — specify the name of an alternate WebLogic Server deployment descriptor (weblogic-application.xml) to use for deployment.

altappdd — specify the name of an alternate J2EE deployment descriptor (application.xml).


The WebLogic 8 adapter is included in the deployment configuration file using the odAdapter element. See “Configuring Delivery Adapters” on page 210 for a description of the odAdapter element and its attributes.

To configure your deployment to use the WebLogic 8 application server adapter, follow these steps:



<odAdapter name="WLAppServerAdapter"class="com.interwoven.od.adapter.delivery.appserver.weblogic.

WLAppServerAdapter" parameter="WebLogicAppServerCfg_path" logLevel="DEBUG"async="no"/>

</odAdapterSet>

where WebLogicAppServerCfg_path is the full path to the WebLogic application server configuration file.

Use of “Upload” Directory

When using OpenDeploy with the WebLogic 8 application server delivery adapter, avoid using the upload directory in the application server directory structure as the target directory for the deployment. Uploading applications to the upload directory will prevent you from being able to roll back an application to an older version. The WebLogic 8 application server appears to only allow new files to get uploaded to that directory.



Instead, use OpenDeploy to deploy content to any other part of the file system on the application server host. The delivery adapter will invoke the appropriate WebLogic 8 commands to pick up and install the application.


OpenDeploy includes a delivery adapter that supports application provisioning in archive or exploded format to BEA Systems WebLogic 9 application servers.


The WebLogic 9 adapter requires the presence of an associated XML-based configuration file. This configuration file contains the settings to run the WebLogic 9 adapter.

The WebLogic 9 configuration file can reside anywhere on the target host. You must specify the full path to this file in the deployment configuration file, which is explained in the following section.


<WLAppServerxmlns="http://interwoven.com/od/adapter/wlappserver"schemaVersion="1.0" name="WebLogic AppServer 9 config file"javaHome="C:\bea\jdk150_03"weblogicJar="C:\bea\weblogic90\server\lib\weblogic.jar"><connection protocol="t3" server="localhost" port="7001"/><userCredentials userName="weblogic" password="weblogic"/><command><deploy targets="examplesServer" deploymentName="exampleServerName"

explodedFormat="true"/></command>

</WLAppServer>

A sample configuration file (WebLogicAppServer9Cfg_example.xml) is included in the following location:

od-home/adapters/delivery/appserver/weblogic/conf


The WebLogic 9 adapter is included in the deployment configuration file using the odAdapter element. See “Configuring Delivery Adapters” on page 210 for a description of the odAdapter element and its attributes.

To configure your deployment to use the WebLogic 8 application server adapter, follow these steps:


451

Delivery Adapters


<odAdapterSet><odAdapter name="WLAppServerAdapter"class="com.interwoven.od.adapter.delivery.appserver.weblogic.

WLAppServerAdapter" parameter="WebLogicAppServerCfg_path" logLevel="DEBUG"async="no"/>

</odAdapterSet>

where WebLogicAppServerCfg_path is the full path to the WebLogic application server configuration file.

The elements and attributes used in the WebLogic 9 adapter configuration file are listed in the associated schema file (WLAppServerAdapter.xsd). This file resides in the following location:

od-home/adapters/delivery/appserver/weblogic/schema

Refer to annotations in this schema file for descriptions of each item.

The following table shows the relationship between certain attributes used in the WebLogic 9 adapter configuration file, and command-line options used with WebLogic 9:

Attributes Option

userConfigFile -userconfigfile

customTrustKS -Dweblogic.security.CustomTrustKeyStoreFileName={filename}

-Dweblogic.security.TrustKeystoreType=CustomTrust

protocolserverport

-adminurl [protocal://]server:port

userName -username username

password -password password


IBM WebSphere Adapters


OpenDeploy includes delivery adapters that support application provisioning to IBM WebSphere application and portal servers. Adapter settings include application installation or update, delivery to servers or clusters, deployment of configuration metadata, and more.

A payload adapter is also provided for extracting configuration metadata from a development portal for deployment to a production portal. See “IBM WebSphere Portal” on page 490 for more information.


The WebSphere adapter requires the presence of an associated XML-based configuration file. This configuration file contains the settings to run the WebSphere adapter.

The WebSphere configuration file can reside anywhere on the target host. You must specify the full path to this file in the deployment configuration file, which is explained in the following sections.

Sample configuration files for both application server (WebSphereAppServerCfg_example.xml) and portal server (WebSpherePortalCfg_example.xml) are included in the following location:

od-home/adapters/delivery/appserver/websphere/conf

The following sections describe WebSphere adapter configuration files for the application server and portal server.

Application Server

The following is an example of the application server configuration file:

<!DOCTYPE websphere SYSTEM "file:///od-home/adapters/delivery/appserver/websphere/dtd/WebSphereAppServer.dtd">

<websphere><appsvr><wsadmin exec="C:\PROGRA~1\WebSphere\DeploymentManager\bin\

wsadmin.bat"/><application serverClusterFlag="server"

svrOrClusterName="servername" node="nodename" filename="ear/war/jar filename" appName="appname"><action name="Install" startAppFlag="true"><taskoptions>"{-contextroot /dir1/dir2 -distributeApp

-installdir c:/temp -nopreCompileJSPs}"</taskoptions></action>

</application></appsvr>

</websphere>

453

Delivery Adapters

You must update the DOCTYPE to include the full path to the WebSphereAppServer.dtd on your host using the following syntax:

<!DOCTYPE websphere SYSTEM "file:///od-home/adapters/delivery/appserver/websphere/dtd/WebSphereAppServer.dtd


The WebSphere application server configuration file contains the root element websphere.

Within the websphere container element, the appsvr element defines the configuration file as pertaining to the WebSphere application server.

Within the appsvr element is the wsadmin element. The wsadmin element defines the administrative settings for the application server. The wsadmin element contains the following attributes:

exec — specify the absoluate path of the wsadmin command on the target host.

userName — specifies the user name used to connect to the administration service. When the administration service is not being run the secure mode, this attribute is not required. You can specify an empty string for the value.

password — specifies the password used with the user name. When the administration service is not being run the secure mode, this attribute is not required. You can specify an empty string for the value.

passwordEncoded— indicates whether (yes) or not (no) the password is encoded. Use the iwodpasscoder command-line tool to generate the encoded password. Default value is yes. Refer to “iwodpasscoder” on page 40 in the OpenDeploy Reference for more information on this tool.

host — specify the host on which the WebSphere administration service runs. Specify this value when the WebSphere application server or network deployment manager runs on a remote server.

port — specify the port number on which the WebSphere administration service listens. Specify this value when the WebSphere application server or network deployment manager runs on a remote server.

Also within the appsvr element is the application element. The application element defines the settings of the application. The application element contains the following attributes:

serverClusterFlag — indicate whether the application is a server or a cluster. The default value is server.

svrOrClusterName — specify the name of the server or cluster application.

node — specify the host name on which the application is being run.

filename — specify the complete name for the associated .ear, .war, or .jar file. It is not necessary to include the path.



appName — specify the name for the application being installed.

Within the application element is the action element. The action element defines the activities of the deployment. The action element contains the following attributes:

name — specify one of the following values:

Install — installs a new application or to install over the existing application. This is the default value. When installing over an existing application, the exising application will be uninstalled first.

Update — updates an existing application. During the update, the old and new configuration will be “merged” (the update will be installed on top of old application without uninstalling the old application, resulting in a merge of old and new configuration content).

Uninstall — uninstalls the application.

startAppFlag — indicate whether (true) or not (false) to start the application after an installation or update (as specified by the name attribute values Install and Update, respectively). The value is ignored if Uninstall is specified as the name attribute value. Default is true.

Within the action element is the taskoptions element. The taskoptions element defines any additional task options to be performed by the adapter. The options must use the JACL syntax. Refer to the following Web site for the JACL syntax and task options:

http://www-306.ibm.com/software/webservers/appserv/infocenter.html

Note that this Web site can change at any time.

The following is an example of the task options

<taskoptions>"{-contextroot /dir1/dir2 -distributeApp -installdir c:/temp -nopreCompileJSPs}"</taskoptions>

Ensure that all the options are in the JACL list (enclosed in the curly braces (“{}”)). You must also enclose the list with double quotes.

Portal Server

The following is an example of the portal server configuration file:


<websphere><portal><xmlaccess exec="websphere-home\xmlaccess.bat" userName="username"password="password" passwordEncoded="yes" host="hostname"port="9081" filename="configFileName"/>

</portal></websphere>

455

Delivery Adapters


<!DOCTYPE websphere SYSTEM "file:///od-home/adapters/delivery/appserver/websphere/dtd/WebSphereAppServer.dtd


The WebSphere portal server configuration file contains the root element websphere.

Within the websphere container element, the portal element defines the configuration file as pertaining to the WebSphere portal server.

Within the portal element is the xmlaccess element. The xmlaccess element defines the settings associated with the xmlaccess tool used with the portal server. Associated with the xmlaccess element are the following attributes:

exec — specify the absoluate path of the xmlaccess tool on the target host. Refer to your WebSphere portal server documentation on how to set up the tool.

userName — specifies the user name used to connect to the portal server.

password — specifies the password used with the ID value to connect to the portal server.

passwordEncoded — indicates whether (yes) or not (no) the password is encoded. Use the iwodpasscoder command-line tool to generate the encoded password. Refer to “iwodpasscoder” on page 40 in the OpenDeploy Reference for more information on this tool. Default value is no.

host — specify the host name of the portal server.

port — specify the port number of the portal server.

filename — specify an XML-based configuration file to be used by the xmlaccess tool to import a portal configuration or a part of it (for example portlets) into the WebSphere portal server.




The WebSphere adapter is configured in the deployment configuration file using the odAdapter element. See “Configuring Delivery Adapters” on page 210 for a description of the odAdapter element and its attributes.

The configuration differs depending on which kind of adapter you are using.

Application Server

To configure your deployment to use the WebSphere Application Server adapter, follow these steps:

1. Open the deployment configuration file using your favorite text or XML editor. You can also use the OpenDeploy deployment configuration composer for this task.

2. Add the following elements and attributes within the target element of the adapter configuration file:<odAdapterSet>

<odAdapter name="WebSphereAppServerAdapter"class="com.interwoven.od.adapter.delivery.appserver.websphere.

IWODIBMAppSvrDeliveryAdapter"parameter="WebSphereAppServerCfg_path"/>

</odAdapterSet>

where WebSphereAppServerCfg_path is the full path to the WebSphere application server configuration file.

Portal Server

To configure your deployment to use the WebSphere Portal Server adapter, follow these steps:


2. Add the following elements and attributes within the target element of the adapter configuration file:<odAdapterSet>

<odAdapter name="WebSpherePortalServerAdapter"class="com.interwoven.od.adapter.delivery.appserver.websphere.

IWODIBMPortalDeliveryAdapter"parameter="WebSpherePortalCfg_path"/>

</odAdapterSet>

where WebSpherePortalCfg_path is the full path to the WebSphere portal server configuration file.

457

Delivery Adapters

BEA Bulk Loader Adapter

OpenDeploy includes a delivery adapter for bulk loading content and metadata into a BEA WebLogic portal server repository. OpenDeploy is used to deploy the content files and their associated metadata files, which are in a format expected by the bulk loader utility. The delivery adapter processes the deployed content by invoking the bulk loader, which in turn updates the portal server repository. You can specify the BEA bulk loader repository as being either a database or a file system.


The BEA bulk loader adapter requires the presence of an associated XML-based configuration file. This configuration file includes the settings to run the adapter.

The BEA bulk loader adapter configuration file can reside anywhere on the target host. You must specify the full path to this file in the deployment configuration file, which is explained in the following section.


<!DOCTYPE BEABulkLoader SYSTEM "file:///od-home/adapters/delivery/appserver/beabulkloader/dtd/BEABulkLoader.dtd">

<BEABulkLoader><load userName="system" password="weblogic" passwordEncoded="no" loaderClasspath="C:\bea\weblogic81\server\lib\weblogic.jar;C:\bea\weblogic81\portal\lib\content.jar;C:\bea\weblogic81\p13n\lib\p13n_system.jar" adminurl="t3://localhost:7001"appName="SampleApplication" repositoryType="ds"repository="BEA_Repository" baseDirectory="C:\testdir\cm_data"/>

</BEABulkLoader>

You must update the DOCTYPE to include the full path to the BEABulkLoader.dtd on your host using the following syntax:

<!DOCTYPE BEABulkLoader SYSTEM "file:///od-home/adapters/delivery/appserver/beabulkloader/dtd/BEABulkLoader.dtd


Here is a description of the elements and attributes associated with the BEA bulk loader delivery adapter configuration file:

BEABulkLoader element — defines the container for the configuration file.


BEA Bulk Loader Adapter

load element — defines the settings for the adapter. The following attributes are associated with this element:

userName — specify the user connecting to the WebLogic application server administration console.


passwordEncoded — indicate whether (yes) or not (no) the password is encrypted. Use the iwodpasscoder OpenDeploy command-line tool to generate the encoded password. Refer to “iwodpasscoder” on page 40 in the OpenDeploy Reference for more information on this tool. Default value is no.

loaderClassPath — specify the full path of the BEA loader classpath. This classpath should contain the following:

• bea-home/server/lib/weblogic.jar

• bea-home/p13n/lib/p13n_system.jar

• bea-home/portal/lib/content.jar

where bea-home is the home directory for the BEA WebLogic portal server. Each item must be separated by the following:

• Windows — semi-colon (“;“). For example:

loaderClassPath="bea-home/server/lib/weblogic.jar;bea-home/p13n/ lib/p13n_system.jar;bea-home/portal/lib/content.jar"

• UNIX — comma (“,“). For example:

loaderClassPath="bea-home/server/lib/weblogic.jar,bea-home/p13n/lib/p13n_system.jar,bea-home/portal/lib/content.jar"

appName — specify the name of the application.

adminurl — specify the URL to the WebLogic application server administration console.

repositoryType — specify the repository type using one of the following values:

• ds — indicates the repository is a database system. This is the default value.

• fs — indicates the repository is a file system.

repository — specify the base directory of the content that is being loaded.

baseDirectory — specify the name of the BEA repository.

459

Delivery Adapters


The BEA bulk loader adapter is configured in the deployment configuration file using the odAdapter element. See “Configuring Delivery Adapters” on page 210 for a description of the odAdapter element and its attributes.

A sample configuration file (BEABulkloaderCfg_example.xml) is included in the following location:

od-home/adapters/delivery/appserver/beabulkloader/conf

To configure your deployment to use the BEA bulk loader adapter, follow these steps:



<odAdapter name="BulkLoaderAdapter" class="com.interwoven.od.adapter.delivery.appserver.beabulkloader.BulkLoaderAdapter"

parameter="BEABulkloaderCfg_path"/></odAdapterSet>

where BEABulkloaderCfg_path is the full path to the BEA bulk loader adapter configuration file.

Microsoft Application Center Adapter

OpenDeploy includes a delivery adapter that supports the deployment of Windows applications defined within Application Center 2000 clusters. This adapter is included with OpenDeploy on Windows only.


The Microsoft Application Center delivery adapter requires the presence of an associated XML-based configuration file. This configuration file includes the settings to run the adapter.

The Microsoft Application Center adapter configuration file can reside anywhere on the target host. You must specify the full path to this file in the deployment configuration file, which is explained in the following section.




<!DOCTYPE MSAppCenter SYSTEM "file:///od-home/adapters/delivery/ms/dtd/MSAppCenter.dtd">

<MSAppCenter exec="C:\AC2000SP2\program files\Microsoft Application Center\ac.exe">

<ACDeploy passwordEncoded="yes"><DeploymentName>MyACDeployment</DeploymentName><Source>

<NodeName>jdoe-pc</NodeName><Credential userName="interwoven\\jdoe" password="xxx"/>

</Source><Targets>

<NodeName>odwin1</NodeName><NodeName>odwin2</NodeName><Credential userName="interwoven\\jdoe" password="xxx"/>

</Targets><Applications>

<ApplicationName>application1</ApplicationName><ApplicationName>application2</ApplicationName>

</Applications><NoACL/><COMPLUS/>

</ACDeploy></MSAppCenter>

You must update the DOCTYPE to include the full path to the MSAppCenter.dtd on your host using the following syntax:

<!DOCTYPE MSAppCenter SYSTEM "file:///od-home/adapters/delivery/ms/dtd/MSAppCenter.dtd


Here is a description of the elements and attributes associated with the Microsoft Application Center delivery adapter configuration file:

MSAppCenter element — defines the container element for the configuration file. The following attributes are associated with this element:

version — specifies the version of the adapter. This value is fixed as "1.0".

exec — specify the full path to the ac.exe program. This is a command line tool that comes with Microsoft Application Center, and is used for administration purposes. For example:

exec="C:\AC2000SP2\program files\Microsoft Application Center\ac.exe"

ACDeploy element — defines the Microsoft Application Center deployment settings, which are contained as child elements within this element. The following attribute is associated with this element:

passwordEncoded — indicate whether (yes) or not (no) those passwords specified through the Credential element are encrypted. Passwords are always replaced by the string <encrypted> in the log files. Default value is no.

461

Delivery Adapters

DeploymentName element — defines a unique name for the Microsoft Application Center deployment.

Source element — defines the source (the application center cluster controller or cluster member) for the Microsoft Application Center deployment. If omitted, the source is assumed to be local computer where the delivery adapter is running.

Note that Microsoft Application Center does not allow use of credential when source is the local machine. So if the source is the local machine where adapter is running, omit source element in the adapter configuration.

Targets element — defines a list of targets on which to deploy the specified applications. If this element is omitted, the applications will be deployed to the members of the source cluster.

Applications element — defines a container for child elements that specify application center applications. If no applications are specified, the command will deploy all applications from the source.

ApplicationName element — defines a list of applications to deploy (by application name).

ApplicationGUID element — defines a list of applications to deploy (by application GUID).

NoACL element — defines that Access Control Lists (ACLs) should not be deployed. ACLs are deployed by default. ACLs are not deployed on partitions that do not support ACLs (for example, FAT), or in non-domain configurations.

COMPLUS element — defines that COM+ applications should be deployed as part of the Microsoft Application Center deployment job.

NodeName element — defines application center host which is either source or target of application center deployment.

Credential element — defines the credential to be used at application center source or target machine. The following attributes are associated with this element:

userName — specify the user name to use for credentials when authenticating on the computer, which can be supplied as domain\username.

password — specify the password to use for credentials when authenticating on the computer.

You can override the deployment command issued by the adapter by using an alternate form of configuration file, in which you specify the exact deployment command to be issued. Use the Command element in the configuration file to specify the exact application center deployment command.

An example file (MSAppCenterCmdFormCfg_example.xml) resides in the following location:

od-home/adapters/delivery/ms/conf




The Microsoft Application Center adapter is configured in the deployment configuration file using the odAdapter element. See “Configuring Delivery Adapters” on page 210 for a description of the odAdapter element and its attributes.

A sample configuration file (MSAppCenterCfg_example.xml) is included in the following location:


To configure your deployment to use the Microsoft Application Center adapter, follow these steps:



<odAdapterSet><odAdapter name="MSAppCenter"class="com.interwoven.od.adapter.delivery.ms.

IWODMSAppCenterDeliveryAdapter" parameter="MSAppCenterCfg_path"/>

</odAdapterSet>

where MSAppCenterCfg_path is the full path to the Microsoft Application Center adapter configuration file.

463

Delivery Adapters

Microsoft COM+ Adapter

OpenDeploy includes a Microsoft COM+ delivery adapter that supports deployment of COM+ applications. This adapter is included with OpenDeploy on Windows only.


The Microsoft COM+ delivery adapter requires the presence of an associated XML-based configuration file. This configuration file includes the settings to run the adapter.

The Microsoft COM+ delivery adapter configuration file can reside anywhere on the target host. You must specify the full path to this file in the deployment configuration file, which is explained in the following section.


<!DOCTYPE MSCOM SYSTEM "file:///od-home/adapters/delivery/ms/dtd/MSCOM.dtd">

<MSCOM><COMPLUSApplication Name="Shipping" ID="{DA2E824F-37DB-4e56-9CDC-563F71C692EB}"><Properties>

<Property name="Description" value="This is my COMPLUSapplication"/>

<Property name="Activation" value="1" type="Long"/> </Properties> <DLLs>

<DLL name="Shipping.dll" deploymentDir="c:\deployed\componentdll">

<Components>

<Component CLSID="{C5E1B4E3-EBC3-48E4-8272-E7B53B823807}"><Properties>

<Property name="ConstructionEnabled" value="True"type="Bool"/>

<Property name="ConstructorString" value="DRIVER=SQLServer;SERVER=(local);DATABASE=Shipping;Trusted_Connection=Yescode" />

<Property name="ObjectPoolingEnabled" value="True"type="Bool"/>

<Property name="MinPoolSize" value="2" type="Long"/><Property name="MaxPoolSize" value="7" type="Long"/><Property name="CreationTimeout" value="2147483600"type="Long"/>

</Properties> </Component>

<Component CLSID="{CF41CE95-56A8-4159-A96C-95D65F0B2111}"><Properties>

<Property name="ConstructionEnabled" value="True" type="Bool"/>

<Property name="ConstructorString" value="DRIVER=SQLServer;SERVER=(local);DATABASE=Shipping;

Trusted_Connection=Yescode"/> <Property name="ObjectPoolingEnabled" value="True"type="Bool"/>


</Properties> </Component>

<Component CLSID="{BA4F38E0-1AA3-4964-BE61-2AA5E0C56D60}"><Properties>

<Property name="ConstructionEnabled" value="True"type="Bool"/>

<Property name="ConstructorString" value="DRIVER=SQLServer;SERVER=(local);DATABASE=Shipping;Trusted_Connection=Yescode" />

<Property name="ObjectPoolingEnabled" value="True"type="Bool"/>


</Properties> </Component>

</Components> </DLL><DLL name="ShippingEvent.dll" deploymentDir="c:\deployed\eventdll" isEventDLL="yes"><Components>

<Component CLSID="{4C2B0940-531A-4C70-B14A-73AC90B2CE39}"></Component>

</Components> </DLL>

</DLLs> </COMPLUSApplication>

</MSCOM>

You must update the DOCTYPE to include the full path to the MSCOM.dtd on your host using the following syntax:

<!DOCTYPE MSCOM SYSTEM "file:///od-home/adapters/delivery/ms/dtd/MSCOM.dtd


Here is a description of the elements and attributes associated with the Microsoft COM+ delivery adapter configuration file:

MSCOM element — defines the container element for the configuration file. The following attribute is associated with this element:

version attribute — specify the version of the adapter. This value is fixed as 1.0.

465

Delivery Adapters

COMPLUSApplication element — defines information regarding the COM+ application. The following attributes are associated with this element:

ID attribute — specify the GUID representing the application.

Name attribute — specify the name of the application.

Properties element — defines the container element for individual properties.

DLLs element — defines the container element for individual DLLs.

DLL element — defines an individual DLL and its associated attributes. The following attributes are associated with this element:

name attribute — specify the name of the DLL.

deploymentDir attribute — specify the full path to the directory where the adapter copies the received files. The received files in this location are used by the COM+ application.

Note that contents of the directory specified by this attribute should not be altered except by the adapter itself. Otherwise, adapter behavior can become unstable.

typeLibrary attribute — specify the name of the external type library file.

proxyStubDLL attribute — specify the name of the proxy-stub DLL.

isEventDLL attribute — indicate whether (yes) or not (no) the DLL contains an event class that should be installed in the COM+ application. Default value is no.

attemptAppDeleteOnDLLDelete attribute — indicate whether (yes) or not (no) the application should be deleted, if after a DLL is deleted, the application has no more components. If disabled, (attemptAppDeleteOnDLLDelete="no") the application is restarted to operate with the remaining components.

Components element — defines the container element for individual components.

Component element — defines an individual component and its associated attribute. The following attribute is associated with this element:

CLSID attribute — specify the class identifier for the component.

Property element — defines an individual property and its associated attributes. The following attributes are associated with this element:

name attribute — specify the name of the property. This value must be a valid property for the object, as specified in the Microsoft documentation.

value attribute — specify the value of the property. This value must be consistent with type of property as specified in the Microsoft documentation.

type attribute — specify one of the following property type values:• Long

• Bool

• String

Default value is string.



If the value attribute is an ENUM, it must be specified by its numeric equivalent. For example, if you configure your COMPLUSApplication element with an Activation property value of COMAdminActivationInproc, you must specify the Property element as:

<Property name="Activation" value="0" type="Long"/>


The Microsoft COM+ delivery adapter is configured in the deployment configuration file using the odAdapter element. See “Configuring Delivery Adapters” on page 210 for a description of the odAdapter element and its attributes.

A sample configuration file (MSCOMCfg_example.xml) is included in the following location:


To configure your deployment to use the Microsoft COM+ delivery adapter, follow these steps:



<odAdapterSet><odAdapter class="com.interwoven.od.adapter.delivery.ms.IWODMSCOMDeliveryAdapter"parameter="MSCOM+_path"/>

</odAdapterSet>

where MSCOM+_path is the full path to the Microsoft COM+ delivery adapter configuration file.

467

Delivery Adapters

Microsoft Global Assembly Cache (GAC) Adapter

OpenDeploy includes a Microsoft Global Assembly Cache (GAC) provisioning adapter to manage deployment of Windows .NET assemblies into global assembly cache (GAC) by invoking the Microsoft Gacutil tool. This adapter is included with OpenDeploy on Windows only.


The Microsoft GAC adapter requires the presence of an associated XML-based configuration file. This configuration file includes the settings to run the adapter.

The Microsoft GAC adapter configuration file can reside anywhere on the target host. You must specify the full path to this file in the deployment configuration file, which is explained in the following section.


<!DOCTYPE MSGAC SYSTEM "file:///od-home/adapters/delivery/ms/dtd/MSGAC.dtd">

<MSGAC gacutilPath="c:\vstud_dotnet\FrameworkSDK\Bin\gacutil.exe"><GlobalAssembly assemblyDLLName="person.dll" force="no"nologo="yes"><ReferenceInfo scheme="OPAQUE" id="Insert some ID here"

description="This is a funky assembly"/><AssemblyNameToUninstall assemblyName="person, Version=1.0.0.0,Culture=neutral, PublicKeyToken=104b3906fabf7a32"/>

</GlobalAssembly></MSGAC>

You must update the DOCTYPE to include the full path to the MSGAC.dtd on your host using the following syntax:

<!DOCTYPE MSGAC SYSTEM "file:///od-home/adapters/delivery/ms/dtd/MSGAC.dtd


Here is a description of the elements and attributes associated with the Microsoft GAC adapter configuration file:

MSGAC element — defines the container element for the configuration file. The following attributes are associated with this element:

version attribute — specify the version of the adapter. This value is fixed as 1.0.

gacutilPath attribute — specify the absolute path to the Gacutil.exe tool provided by Microsoft.


Microsoft Global Assembly Cache (GAC) Adapter

GlobalAssembly element — defines settings related to a global assembly. The following attributes are associated with this element:

assemblyDLLName attribute — specify the name of DLL that contains the global assembly.

force attribute — indicate whether (yes) or not (no) to use the Gacutil tool’s /f option. Enabling this feature ("force=yes") suppresses the /r option which is specified through ReferenceInfo element in the configuration. Default value is no.

silent attribute — indicate whether (yes) or not (no) to use the Gacutil tool’s silent option. Default value is no.

nologo attribute — indicate whether (yes) or not (no) to use the Gacutil tool’s nologo option. Default value is no.

ReferenceInfo element — defines how assembly installs and uninstalls will be reference counted. The associated attributes are used to construct the arguments required for Gacutil.exe tool’s /r option.The following attributes are associated with this element:

scheme attribute — refer to your Microsoft documentation regarding the scheme parameter associated with the Gacutil tool’s /r option.

id attribute — refer to your Microsoft documentation regarding the scheme parameter associated with the Gacutil tool’s /r option.

description attribute — refer to your Microsoft documentation regarding the scheme parameter associated with the Gacutil tool’s /r option.

AssemblyNameToUninstall element — defines the assembly to uninstall. You can specify multiple AssemblyNameToUninstall elements, resulting in multiple assemblies being uninstalled. When the OpenDeploy target server notices that the DLL referenced by the assemblyDLLName attribute has been deleted, it invokes the Gacutil tool to uninstall all the assemblies referenced using the AssemblyNameToUninstall elements.The following attribute is associated with this element:

assemblyName attribute — specify the name of assembly to uninstall.


The Microsoft GAC adapter is configured in the deployment configuration file using the odAdapter element. See “Configuring Delivery Adapters” on page 210 for a description of the odAdapter element and its attributes.

A sample configuration file (MSGACfg_example.xml) is included in the following location:


To configure your deployment to use the Microsoft GAC adapter, follow these steps:


469

Delivery Adapters


<odAdapterSet><odAdapter class="com.interwoven.od.adapter.delivery.ms.IWODMSGACDeliveryAdapter" parameter="MSGAC_path"/>

</odAdapterSet>

where MSGAC_path is the full path to the Microsoft GAC adapter configuration file.

SunCIS

You can archive files on a standalone OpenDeploy server using the Sun Content Infrastructure System (SunCIS) delivery adapter. Archiving files in this manner does not require you to install the Archival module, but your OpenDeploy server must still have the Archival module license.

To use the SunCIS delivery adapter, update your deployment configuration’s odAdapterSet element with the following odAdapter element:

<odAdapterSet><odAdapter name="SunCISAdapter" class="com.interwoven.od.adapter.delivery.sunCIS.SunCISAdapter" parameter="retention_number"/>

...</odAdapterSet>

where retention_number is the number of days that the files are retained on the WORM device. There is no default value for this attribute.

Use of OpenDeploy with the SunCIS delivery adapter is similar to other delivery adapters. However, unlike other delivery adapters, there is no corresponding configuration file.


Appendix B

Payload Adapters

This appendix lists and describes the payload adapters that have been tested and approved for use with OpenDeploy. See “Payload Adapter-Based Deployments” on page 121 for instructions on how to configure deployments using payload adapters.

Note: Use of payload adapters with EasyDeploy is not supported.

JDK Requirement

If you intend to use payload adapters, you must install the appropriate Java Development Kit (JDK). Refer to “JDK” on page 24in the OpenDeploy Release Notes for the supported versions of the JDK.

Sample Adapters

OpenDeploy provides the following sample payload adapters:

GenericRetrievalExample — a sample payload adapter that accepts CDATA string data input.

QueryRetrievalExample — a sample payload adapter that accepts queries.

These sample payload adapters can be used as the basis for implementing your own payload adapters. Comments are included in the adapter source code.

These sample adapters are provided with the OpenDeploy base server in the following location:

od-home/adapters/payload/example

471

Payload Adapters

File List Differential Adapter

OpenDeploy provides a file list differential payload adapter that compares files specified in a user-defined file list with the contents of the target file location. Those files that are different can be deployed or deleted as per the specified action in the deployment configuration, similar to other payload adapters.

Configuration

To perform a file list differential deployment, you must specify the IWFilelistCompare adapter in the payLoadProperties element in the deployment configuration or the source host’s base server configuration file, for example:

<payLoadProperties name="iwov" class="com.interwoven.od.adapter.payload.filelist.IWFilelistCompare"/>

See “Specifying the Payload Adapter” on page 123 for more information.

A file system value must be provided for the deployment configuration’s area attribute value associated with the payload element. Use the file system equivalent if you want to deploy from a TeamSite area. See “Specifying TeamSite Areas” on page 103 for more information.

In the deployment configuration, you must include the absolute path to your user-provided file list as CDATA within the payLoadRules element, for example:

<payload area="...">...<payLoadRules><custom>

<![CDATA[/export/home/filelist.txt]]></custom><action name="deploy"/>




File List Differential Adapter

Editing the File List

See “Editing the File List” on page 117 for general information on how to compose the file list entries.

All entries in the file list used by the file list differential adapter must contain absolute paths, for example:

C:\website\files\www\index.htmlC:\website\files\www\andre\index.htmlC:\website\files\www\products.html

or

/dev/development/website/files/www/index.html/dev/development/website/files/www/andre/index.html/dev/development/website/files/www/products.html

This differs from a traditional file list deployment where the file list entries are paths relative the specified source file location.

TeamSite vpaths, for example:

//IWSERVER/dev/main/website/EDITION/ed001/files/www/index.html

are not supported. Use the file system equivalent for the full path of each entry.

All entries in the file list must be present in the source file location specified by the payload element’s area attribute value. Files not present in that location will not be deployed.

473

Payload Adapters

Database Adapters

OpenDeploy provides the following payload adapters as part of the Intelligent Delivery module for performing metadata-based deployments. These adapters are enabled only if the OpenDeploy Intelligent Delivery module is installed and licensed on the source host:

IWQueryDatabaseRetrieval — in this adapter, the query specifications follow the predefined format listed in the query.dtd DTD file. For example:<payLoadProperties name="queryDBAdapter"

class="com.interwoven.od.adapter.retrieval.database.IWQueryDatabaseRetrieval"

parameter="driver=DRIVERNAME, classpath=CLASSPATH_OF_DRIVER,url=URL, user=USER, password=PASSWORD, table=TABLENAME"

logLevel="level"/></payLoadProperties>

The adapter translates the query into a SQL call and returns a manifest of files matching the query.

Use this database adapter when you are using the OpenDeploy query syntax, as specified by the presence of the query element in the payLoadRules element in the query element in the deployment configuration file.

IWGenericDatabaseRetrieval — in this adapter, the query specifications are supplied as an SQL statement defined by the user. For example:<payLoadProperties name="genericDBAdapter"

class="com.interwoven.od.adapter.retrieval.database.IWGenericDatabaseRetrieval"

parameter="driver=DRIVERNAME, classpath=CLASSPATH_OF_DRIVERurl=URL, user=USER, password=PASSWORD" logLevel="level"/>


The adapter translates the query into a SQL call and returns a manifest of files matching the query.

Use this database adapter when you are specifying your query as PCDATA within the payLoadRules element in the deployment configuration file.

For the parameter attribute, the following name-value parameter pairings are required for these adapters:

driver — specify the payload adapter driver.

classpath — specify the path to the JDBC driver file.

url — specify the database URL.

user — specify the user name associated with the database.


table — (IWQueryDatabaseRetrieval only) specify the table name of the database.

See “Metadata-Based Deployments” on page 130 for more information about how these database adapters are used.


Software Configuration Management Adapters


OpenDeploy provides software configuration management (SCM) adapters supporting the following vendors:

IBM Rational ClearCase

Microsoft Visual SourceSafe (VSS) (included with OpenDeploy on Windows only)

Serena (Merant) PVCS

Concurrent Versions System (CVS)

MKS Source Integrity

An SCM adapter enables OpenDeploy to extract files from an SCM repository at the beginning of a deployment.

IBM Rational ClearCase Adapter

To configure the ClearCase payload adapter, add the following configuration to your deployment or base server configuration file:

<payLoadProperties name="ClearCaseAdapter" class="com.interwoven.od.adapter.payload.scm.clearcase.IWODClearCaseAdapter" parameter="" logLevel=”level”/>


In order to use the ClearCase payload adapter, the OpenDeploy base server must run as a user with sufficient authority to access a ClearCase view.


You must provide a valid configuration file for the ClearCase adapter. This is an XML-based file that can reside anywhere on the deployment source host. This file is referenced in the deployment configuration.

You can configure one of the following types of ClearCase commands:

Checkout — creates a modifiable copy of a version.

Update — updates elements in a snapshot view.

Sample configuration files for the checkout (ClearCaseCheckoutConfig_example.xml) and update (ClearCaseUpdateConfig_example.xml) commands reside in the following location:

od-home/adapters/payload/scm/clearcase/conf

475

Payload Adapters

In the deployment configuration, provide the full path to the ClearCase adapter configuration file as a CDATA string within the custom child element of the payLoadRules element. For example:

<payLoadRules><action name="deploy"/><custom>od-home/adapters/payload/scm/clearcase/conf/ClearCaseUpdateConfig.xml</custom>

</payLoadRules>

The following examples show each type of configurations.

Checkout Command<!DOCTYPE clearcase SYSTEM "file:///od-home/adapters/payload/

scm/clearcase/dtd/ClearCaseScm.dtd"><clearcase name="clearcase checkout"

execPath="C:\program files\Rational\ClearCase\bin"><clearcaseCheckout reserved="yes" noData="no" preserveTime="yes" noWarn="yes" comment="test"><clearcaseItem itemPath="C:\view\viewfile1"/><clearcaseItem itemPath="C:\view\viewfile2"/>

</clearcaseCheckout></clearcase>

Update Command<!DOCTYPE clearcase SYSTEM "file:///od-home/adapters/payload/scm/

clearcase/dtd/ClearCaseScm.dtd"><clearcase name="clearcase get" execPath="C:\program files\

Rational\ClearCase\bin"><clearcaseUpdate overwrite="yes" rename="no" currentTime="yes" log="log.log"><clearcaseItem itemPath="c:\views\viewdir"/>

</clearcaseUpdate></clearcase>

You must update the DOCTYPE to include the full path to the ClearCaseScm.dtd on your host using the following syntax:

<!DOCTYPE clearcase SYSTEM "file:///od-home/adapters/payload/scm/clearcase/dtd/ClearCaseScm.dtd">


Here is a listing of the elements and attributes associated with this configuration file.

clearcase element — defines the general settings associated with using the ClearCase adapter. This element has the following attributes:

name — specify the name for this ClearCase configuration.

execPath — (required) specify the full path to the cleartool executable file.



clearcaseCheckout element — defines the settings associated with the Checkout command. This element has the following attributes:

reserved — indicate whether (yes) or not (no) to check out the file as reserved or not. Default value is yes.

noData — indicate whether (yes) or not (no) to check out the file, but do not create an editable file containing its data Default value is no.

preserveTime — indicate whether (yes) or not (no) to preserve the modification time of the file being checked out. Default value is no.

branch — specify a branch from which to check out the file.

version — indicate whether (yes) or not (no) to allow checkout of a version other than main latest. Default value is no.

noWarn — indicate whether (yes) or not (no) to suppress warning messages. Default value is no.

comment — specify a comment string for all the event records created by the command. If there is more than one occurrence of the comment attribute, only the first occurrence is used. The others are ignored. If no occurrence is specified, no comments are used by this command.

commentFile — specify the path to a text file in whose contents are to be placed in all the event records created by this command. If there is more than one occurrence of the commentfile attribute, only the first occurrence is used. The others are ignored. If no occurrence is specified, no comments are used by this command.

clearcaseUpdate element — defines the settings associated with the Update command. This element has the following attributes:

overwrite — indicate whether (yes) or not (no) to overwrite hijacked files (see below). If enabled (overwrite="yes") ClearCase overwrites all the hijacked files with the version selected by the configuration. Default value is no.

A “hijacked file” is a version in a snapshot view that is modified but not checked out. By default, a non-checked-out version in a snapshot view is given the file attribute of read-only. If you change this attribute and modify the file, you have hijacked the file by taking it out of direct ClearCase control.

rename — indicate whether (yes) or not (no) hijacked files (see above) should be renamed with a .keep extension. If enabled (rename="yes") ClearCase renames hijacked files to filename.keep and copies the version in the versioned object base (VOB) selected by the configuration into the view. Default value is no.

A VOB is a repository that stores version of file elements, directory elements, derived objects, and metadata associated with these objects.

currentTime — indicate whether (yes) or not (no) the modification time should be written as the current time. Default value is no. This attribute cannot be used with the preservetime attribute.

preserveTime — indicate whether (yes) or not (no) the modification time should preserved from the VOB time. Default value is no. This attribute cannot be used with the currenttime attribute.

477

Payload Adapters

log — specify the full path to the ClearCase log file.

clearcaseItem element — defines a specific ClearCase item, such as a ClearCase project or file path. You can specify multiple clearcaseItem elements within the configuration. This element has the following attribute:

itemPath — (required) specify a project database, project, folder, or versioned file from which you want to check out a revision.

Refer to the associated DTD (ClearCaseScm.dtd) for a list of syntax rules. This file resides in the following location:

od-home/adapters/payload/scm/clearcase/dtd

Microsoft Visual SourceSafe

This adapter is included with OpenDeploy on Windows only.

To configure the Microsoft Visual SourceSafe (VSS) payload adapter, add the following configuration to your deployment or base server configuration file:

<payLoadProperties name="VssAdapter"class="com.interwoven.od.adapter.payload.scm.vss.IWODVssAdapter" parameter="" logLevel=”level”/>



You must provide a valid configuration file for the VSS adapter. This is an XML-based file that can reside anywhere on the deployment source host. This file is referenced in the deployment configuration.

You can configure one of the following types of VSS commands:

Checkout — retrieves a read-only copy of the specified VSS files.

Get — copies a file from the current project to the working directory, for the purpose of editing.

Sample configuration files for the checkout (VssCheckoutConfig_example.xml) and get (VssGetConfig_example.xml) commands reside in the following location:

od-home/adapters/payload/scm/vss/conf



In the deployment configuration, provide the full path to the VSS adapter configuration file as a CDATA string within the custom child element of the payLoadRules element. For example:

<payLoadRules><action name="deploy"/><custom>od-home/adapters/payload/scm/vss/conf/VssGetConfig.xml</custom>

</payLoadRules>

The following examples show each type of configurations.

Checkout Command<!DOCTYPE vss SYSTEM "file:///od-home/adapters/payload/scm/vss/

dtd/VssScm.dtd"><vss name="VssConfig" execPath="C:\Program Files\

Microsoft Visual Studio\Common\VSS\win32"><vssCheckout serverPath="\\VssServer\VssPath\" userName="userName"password="password" passwordEncoded="yes" localPath="C:\temp\vss" autoResponse="yes" comment="Checkout Test" output="C:\temp\vss.output" recursive="yes" fileTimestamp="modified" writableFiles="replace"version="12" date="2-29-99" label="label Beta 1"><vssItem itemPath="$/myproject/project1"/><vssItem itemPath="$/myproject/project2"/>

</vssCheckout></vss>

Get Command<!DOCTYPE vss SYSTEM "file:///od-home/adapters/payload/scm/vss/

dtd/VssScm.dtd"><vss name="VssConfig" execPath="C:\Program Files\

Microsoft Visual Studio\Common\VSS\win32"><vssGet serverPath="\\VssServer\VssPath\" userName="userName"password="password" passwordEncoded="yes" localPath="C:\temp\vss" autoResponse="yes"output="C:\temp\vss.output" recursive="yes" writable="no"fileTimestamp="modified" writableFiles="replace" version="12"date="2-29-99" label="label Beta 1"><vssItem itemPath="$/myproject/project1"/><vssItem itemPath="$/myproject/project2"/>

</vssGet></vss>

You must update the DOCTYPE to include the full path to the ClearCaseScm.dtd on your host using the following syntax:

<!DOCTYPE vss SYSTEM "file:///od-home/adapters/payload/scm/vss/dtd/VssScm.dtd">


Here is a listing of the elements and attributes associated with this configuration file:

479

Payload Adapters

vss element — defines identity information on the adapter. This contains the following attributes:

name — specify the name for this VSS configuration.

execPath — (required) specify the full path to the VSS executable file path.

vssCheckout element — defines the checkout command for VSS. This element contains the following attributes:

serverPath — (required) specify the full path to a specific SRCSAFE.INI file.

userName — specify the user's name.

password — specify the user's password.

passwordEncoded — indicate whether (yes) or not (no) the password is encoded. Use the iwodpasscoder OpenDeploy command-line tool to generate the encoded password. Refer to “iwodpasscoder” on page 40 in the OpenDeploy Reference for more information on this tool. Default value is no.

localPath — (required) specify the full path to particular folder, rather than the current or working folder.

autoResponse — indicate whether VSS to answer yes or no to all Yes or No questions.

There are a number of circumstances when VSS commands ask for input from the user (for example, warnings containing Yes or No questions). This is not favorable when writing scripts, macros or programs that execute the VSS command line from inside other programs. Use the autoResponse attribute to instruct VSS on how to answer these type of Yes or No questions. If a default value is not specified, then the system default value is used.

comment — specify the comment for checkout command.

output — specify the full for the command output file.

recursive — indicate whether (yes) or not (no) to recursively get an entire project list. Default value is no.

fileTimestamp — indicate whether to set the local copy time to the current (current), last modified (modified), or last updated (updated) date and time.

writableFiles — indicate whether VSS should replace (replace) or skip (skip) write-only files.

version — specify the version number by which to get the project.

date — specify the date by which to get the project.

label — specify the label by which to get the project.

vssGet element — defines the get command for VSS. This element has the following attributes:

serverPath — (required) specify the full path to a specific SRCSAFE.INI file.

userName — specify the user's name.

password — specify the user's password.



passwordEncoded — indicate whether (yes) or not (no) the password is encoded. Use the iwodpasscoder OpenDeploy command-line tool to generate the encoded password. Refer to “iwodpasscoder” on page 40 in the OpenDeploy Reference for more information on this tool. Default value is no.localpath — (required) specify the full path to particular folder, rather than the current or working folder.

autoResponse — indicate whether VSS to answer yes or no to all Yes/No questions.

output — specify the full for the command output file.

recursive — indicate whether (yes) or not (no) to recursively get an entire project list. Default value is no.

writable — indicate whether (yes) or not (no) to specify that local copies are writable. Otherwise, they are read-only. Default value is no.

fileTimestamp — indicate whether to set the local copy time to the current (current), last modified (modified), or last updated (updated) date and time.

writableFiles — indicate whether VSS should replace (replace) or skip (skip) write-only files.

version — specify the version number by which to get the project.

date — specify the date by which to get the project.

label — specify the label by which to get the project.

vssItem element — defines a specific VSS item, such as a VSS project or file path. You can specify multiple vssItem elements within the configuration. This element has the following attribute:


Refer to the associated DTD (VssScm.dtd) for a list of syntax rules. This file resides in the following location:

od-home/adapters/payload/scm/vss/dtd/VssScm.dtd

481

Payload Adapters

Serena (Merant) PVCS

To configure the PVCS payload adapter, add the following configuration to your deployment or base server configuration file:

<payLoadProperties name="PvcsAdapter" class="com.interwoven.od.adapter.payload.scm.pvcs.IWODPvcsAdapter" parameter="" logLevel=”level”/>



You must provide a valid configuration file for the PVCS adapter. This is an XML-based file that can reside anywhere on the deployment source host. This file is referenced in the deployment configuration.

You can configure the PVCS Get command, which copies a file from the current project to the working directory, for the purpose of editing.

A sample configuration file (PvcsGetConfig_example.xml) resides in the following location:

od-home/adapters/payload/scm/pvcs/conf

In the deployment configuration, provide the full path to the PVCS adapter configuration file as a CDATA string within the custom child element of the payLoadRules element. For example:

<payLoadRules><action name="deploy"/><custom>od-home/adapters/payload/scm/conf/PvcsGetConfig.xml</custom>

</payLoadRules>

The following sample demonstrates shows this configuration:

<!DOCTYPE pvcs SYSTEM "file:///od-home/adapters/payload/scm/pvcs/dtd/PvcsScm.dtd">

<pvcs name="PvcsConfig" execPath="C:\Program Files\Merant\vm\win32\bin"><pvcsGet projectDB="C:\Program Files\Merant\vm\common\SampleDB"userId="userid" password="password" passwordEncoded="yes"localPath="C:\temp\pvcs" autoResponse="yes"output="C:\temp\pvcsoutput" baseProject="/bridge" projectPath="/bridge" recursive="yes" writable="yes"revision="test" version="1.0"><pvcsItem itemPath="hlp"/><pvcsItem itemPath="res"/>

</pvcsGet></pvcs>



You must update the DOCTYPE to include the full path to the PvcsScm.dtd on your host using the following syntax:

<!DOCTYPE pvcs SYSTEM "file:///od-home/adapters/payload/scm/pvcs/dtd/PvcsScm.dtd">


Here is a listing of the elements and attributes associated with this configuration file:

pvcs element — defines the PVCS adapter configuration. This element has the following attributes:

name — specify the name for this PVCS configuration.

execPath — (required) specify the full path to the PVCS executable.

pvcsGet element — defines the get command for PVCS. This element has the following attributes:

projectDB — specify the location of the project database.

userId — specify a user ID.

password — specify a password.

passwordEncoded — indicate whether (yes) or not (no) the password is encoded. Use the iwodpasscoder OpenDeploy command-line tool to generate the encoded password. Refer to “iwodpasscoder” on page 40 in the OpenDeploy Reference for more information on this tool. Default value is no.

localPath — (required) specify the full path to an alternative location for locating workfiles.

autoResponse — indicate whether PVCS should answer yes or no to all Yes/No questions. Default value is no.

There are a number of circumstances when PVCS commands ask for input from the user (for example, warnings containing Yes or No questions). This is not favorable when writing scripts, macros or programs that execute the PVCS command line from inside other programs. Use the autoResponse attribute to instruct PVCS on how to answer these type of Yes or No questions. If a default value is not specified, then the system default value is used.

output — specify the full path to the file where PVCs redirects standard output.

baseProject — specify the relative path to the base project used in computing workfile locations.

projectPath — specify the relative path to the the project or folder to be used.

workSpace — specify the relative path a public or private workspace.

lock — indicate whether (yes) or not (no) to lock the revision with intent to modify it. Default value is no.

recursive — indicate whether (yes) or not (no) to recursively get revisions for versioned files in subprojects. Default value is no.

483

Payload Adapters

writable — indicate whether (yes) or not (no) to make the workfile writable even if not locked. Default value is no.

override — indicate whether (yes) or not (no) override work file location. Default value is yes.

promotionGroup — specify a promotion group.

revision — specify a revision.

version — specify a version.

dateTime — specify a revision by date/time.

fileUseCurrentTime — indicate whether (yes) or not (no) to set the workfile to current date/time. Default value is no.

fileNewerThan — specify the date that the file must be newer than to be included in the get command.

allowBranching — indicate whether (yes) or not (no) to allow a lock to occur if the revision being locked would create a branch upon check-in. Specify a value of yes to create a branch in this case.

If enabled (allowBranching="yes"), the BranchWarn directive is overridden, allowing you to lock a revision even if that will result in a branch upon check in.

If disabled (allowBranching="no") you are prevented locking a revision if a lock would result in a branch upon check in. This option is ignored if the branchWarn directive is not in effect.

allowMultiLock — indicate whether (yes) or not (no) the MultiLock directive is allowed. Specify a value of yes to allow the application of an additional lock.

pvcsItem element — defines a specific PVCS item, such as a PVCS project or file path. You can specify multiple pvcsItem elements within the configuration. This element has the following attribute:


Refer to the associated DTD (PvcsScm.dtd) for a list of syntax rules. This file resides in the following location:

od-home/adapters/payload/scm/pvcs/dtd/PvcsScm.dtd



Concurrent Versions System (CVS)

To configure the CVS payload adapter, add the following configuration to your deployment or base server configuration file:

<payLoadProperties name="CVSAdapter" class="com.interwoven.od.adapter.payload.scm.cvs.IWODCvsAdapter" parameter="" logLevel="level"/>



You must provide a valid configuration file for the CVS adapter. This is an XML-based file that can reside anywhere on the deployment source host. This file is referenced in the deployment configuration.

You can configure the CVS Checkout command, which creates or updates a working directory containing copies of the source files specified by modules. You can then edit these source files at any time; update them to include new changes applied by others to the source repository; or commit your work as a permanent change to the source repository.

A sample configuration file (CVSCheckoutConfig_example.xml) resides in the following location:

od-home/adapters/payload/scm/cvs/conf

In the deployment configuration, provide the full path to the CVS adapter configuration file as a CDATA string within the custom child element of the payLoadRules element. For example:

<payLoadRules><action name="deploy"/><custom>od-home/adapters/payload/scm/conf/CVSCheckoutConfig.xml</custom>

</payLoadRules>


<cvs schemaVersion="1.0" xmlns="http://interwoven.com/od/adapter/cvs"name="CVSCheckoutExample" execPath="/usr/local/bin"><cvsCheckout workingDir="/data/cvs/test/source"><globalOption>

<cvsRepository accessMethod="pserver" userName="lshi"password="AsgGHEertsTSfg==" passwordEncoded="true"cvsServer="myserver" repositoryPath="/data/cvs/repository"/>

</globalOption><checkoutCommandOption force="true" revision="1.5"/><cvsModule modulePath="myproj/src"/><cvsModule modulePath="myproj/include"/>

</cvsCheckout></cvs>

485

Payload Adapters

The elements and attributes used in the CVS adapter configuration file are listed in the associated schema file (CVSAdapter.xsd). This file resides in the following location:

od-home/adapters/payload/scm/cvs/schema


To work with password authentication, you must use the pserver authentication method.

The following table shows the relationship between certain attributes used in the CVS adapter configuration file, and command-line options used with CVS:

Attribute Option

readOnly -r

writable -w

turnOffCmdHistory -1

doNotExecute -n

showTrace -t

tempDir -T tempdir

notUseCvsrc -f

compressionLevel -z gzip-level

authNetTraffic -a

variable, value -s variable=value

resetStickyTag -A

doNotShortModule -N

pruneEmptyDir -P

recursive -R

catModule -c

force -f

local -l

doNotExecuteCheckout -n

checkoutToStdOut -p

catModuleWithStatus -s

revision -r tag

date -D date

checkoutToDir -d dir

useKOption -k kflag

mergeRev1 -j revision



MKS Source Integrity

To configure the MKS payload adapter, add the following configuration to your deployment or base server configuration file:

<payLoadProperties name="MKSAdapter" class="com.interwoven.od.adapter.payload.scm.mks.IWODMKSAdapter"parameter="" logLevel="level"/>



You must provide a valid configuration file for the MKS adapter. This is an XML-based file that can reside anywhere on the deployment source host. This file is referenced in the deployment configuration.

You can configure the MKS Resync command, which compares the contents of project members with their corresponding working files in the MKS “sandbox” and replaces the working file with an exact copy of the member revision, if differences are detected or if no working file exists. This command has no effect on working files that are identical to the member revision.

A sample configuration file (MKSResyncConfig_example.xml) resides in the following location:

od-home/adapters/payload/scm/mks/conf

In the deployment configuration, provide the full path to the MKS adapter configuration file as a CDATA string within the custom child element of the payLoadRules element. For example:

<payLoadRules><action name="deploy"/><custom>od-home/adapters/payload/scm/conf/MKSResyncConfig.xml</custom>

</payLoadRules>

487

Payload Adapters


<mks xmlns="http://interwoven.com/od/adapter/mks" schemaVersion="1.0"name="MKSResyncConfigExample"execPath="C:\Program Files\MKS\IntegrityClient\bin"><mksResync><generalOption hostName="odwin4" port="7001" userName="lshi"

password="password" recurse="true"sandbox="C:\scm\mks\sandbox\ajubabanking\mksproj.pj"><andFilterOption><changed value="all"/>

</andFilterOption><orFilterOption><file expression="*.scc" negate="true"/><label name="testlabel"/>

</orFilterOption></generalOption><resyncOption mergeType="automatic" onMergeConflict="highlight"

byCP="false" includeDropped="true" overwriteChanged="false"/></mksResync>

</mks>

The elements and attributes used in the MKS adapter configuration file are listed in the associated schema file (MKSAdapter.xsd). This file resides in the following location:

od-home/adapters/payload/scm/mks/schema


The following table shows the relationship between certain attributes used in the MKS adapter configuration file, and command-line options used with MKS:

Attribute Option

cwd --cwd=value

selectionFile --selectionFile=file

forceConfirm --forceConfirm=[yes|no]

FilterOptionType --filter=filterOptions

archiveShared archiveshared

attribute attribute:name[=value]

changed changed[:working|:sync|:newer|:size|:missing|:newmem|:all]

rule rule[:defined|:invalid|:memberrevdiffers]

file file:expression

frozen frozen

label label[:name]

anyLabel anylabel[:name]

locked locked[:name]

state state[:name]

format format[:text|:binary]

workingBranch workingbranch


Payload Adapters

IBM WebSphere Portal

The WebSphere Portal adapter enables OpenDeploy to extract configuration metadata from a development portal for deployment to a production portal. See “IBM WebSphere Adapters” on page 453 for more information.

To configure the IBM WebSphere Portal payload adapter, add the following configuration to your deployment or base server configuration file:

<payLoadProperties name="IBMPortalSrcAdapter" class="com.interwoven.od.adapter.payload.portalserver.IWODIBMPortalSrcAdapter" parameter="" logLevel=”level”>




You must provide a valid configuration file for the WebSphere portal adapter. This is an XML-based file that can reside anywhere on the deployment source host. This file is referenced in the deployment configuration.

A sample configuration file (WebSpherePortalConfig_example.xml) resides in the following location:

od-home/adapters/payload/portalserver/conf

In the deployment configuration, provide the full path to the WebSphere portal adapter configuration file as a CDATA string within the custom child element of the payLoadRules element. For example:

<payLoadRules><action name="deploy"/><custom>od-home/adapters/payload/WebSpherePortalConfig.xml</custom>

</payLoadRules>

The following is an example of an IBM WebSphere Portal payload adapter configuration file.


<websphere><portal><xmlaccess exec="c:\ibmtool\xmlaccess.bat" userName="portaladmin"

password="password" passwordEncoded="no" host="hostname"port="9081" filename="c:\ibmtool\export.xml"outputfile="C:\Interwoven\OpenDeployNG\userlib\orion_out.xml"/>

</portal></websphere>


IBM WebSphere Portal




Within the websphere container element, the portal element defines the configuration file as pertaining to the WebSphere portal server.

Within the portal element is the xmlaccess element. The xmlaccess element defines the settings associated with the xmlaccess tool used with the portal server. Associated with the xmlaccess element are the following attributes:

exec — specify the absoluate path of the xmlaccess tool on the target host. Refer to your WebSphere portal server documentation on how to set up the tool.

userName— specify the ID value used to connect to the portal server.

password — specify the password used with the ID value to connect to the portal server.

passwordEncoded — indicate whether (yes) or not (no) the password is encoded. Use the iwodpasscoder OpenDeploy command-line tool to generate the encoded password. Refer to “iwodpasscoder” on page 40 in the OpenDeploy Reference for more information on this tool. Default value is yes.

host — specify the host name of the portal server.

port — specify the port number of the portal server.

filename — specify an XML config file that is used by the xmlaccess tool to export a portal configuration or a part of it (for example, portlets) from the WebSphere portal server.

The exported portlets are saved into a file specified by the outputfile attribute (see below) in the adapter configuration file, which can be used to import back into the WebSphere portal server.

outputfile — specify the full path to the file that contains the exported portal configuration. You must specify a value or an error will occur, with the following entry written to the log file:

Error: no output file created

See “Portal Server” on page 455 for descriptions of the attributes associated with the IBM WebSphere Portal payload adapter configuration file.

491

Payload Adapters


Glossary

This glossary lists terms and their definitions found in this manual.

adapter Java-based program that extends content distribution to specialized devices and protocols, such as edge or cache servers, within the Delivery Adapter Framework.

administration server A server with the OpenDeploy administration software installed. The administration server is responsible for generating and managing the browser-based user interface in the OpenDeploy environment.

Administrator role The highest level of OpenDeploy access. An individual with the Administrator role has the ability to configure OpenDeploy servers, create and start deployment configurations, and set access restrictions for individuals in the User role.

area A file system- or TeamSite-based location where files reside or will reside as the result of a deployment. Files residing in one area can also be compared with files in another area to determine whether they should be deployed.

asynchronous deployment

The practice of starting a deployment, but not waiting for the deployment to end before moving on to other tasks. When a deployment is run asynchronously, only the deployment’s success or failure to start is returned. No indication of the deployment’s success or failure to complete is presented. Asynchronous deployments are only available when using the iwodcmd start command-line tool.

attribute A directive with a corresponding value that can be used to alter the default behavior of OpenDeploy, or that must be used to provide required information.

base server The OpenDeploy software installed on a server that is licensed to send and receive deployments.

base server configuration file

An XML-based file that defines the rules and settings for a base server within the OpenDeploy environment. The base server configuration file must follow the XML rules as defined in the deploy server configuration DTD.

base server log A log file containing entries related to the base server host.

bind port number The number for the port that source and target hosts use to transport deployed files.

493

bootstrap administrator

The initial Administrator role user identity used to assign the Administrator role to other individuals.

certificate A file which assures that both the source and target hosts in an SSL key encrypted deployment are certified to be taking part.

certificate authority A set of programs used to generate public and private key pairs, and a database that contains state information. Certificate authority is used in conjunction with SSL encryption.

cipher An encryption tool that the source and target hosts share to hide the identity of deployed files.

compare phase The period of time during a deployment when files are being compared to determine whether they should be deployed. This is also the time during a deployment when it can be cancelled.

comparison rules Optional criteria to use for determining whether to deploy files from the source host to the target host.

compression The reduction of the size of files using compression algorithms. Compression results in a smaller deployment which speeds the transfer time to targets.

ControlHub A state management server that enables an IT organization to manage assets for different initiatives or applications. ControlHub is built on a high performance repository that stores the assets, and comes with a user interface that organizes, versions and manages those assets.

custom report A method of constructing a report query through the browser-based user interface by entering or selecting search values.

DataDeploy wrapper file

An OpenDeploy deployment configuration that simply contains a path to a DataDeploy configuration file, plus logging rules. When the deployment is run, the DataDeploy configuration file is invoked.

definition The matching of one or more source file locations (either file system locations or TeamSite areas) with a target file location (a file system location) for the purpose of deploying and receiving files. A deployment configuration can have one or more definitions between file locations on the sending host and the target file location.

Delivery Adapter Framework

A framework that enables the creation of application-specific adapters for extending the content delivery capabilities of OpenDeploy. This allows you to extend the reach of your content distribution network to specialized devices and protocols, such as edge or cache servers.

Deploy and Run An OpenDeploy feature that allows external scripts or programs to be integrated into the deployment process.

deploy server configuration DTD

The XML-based DTD upon which the base server and receiver configuration files is derived.

deployment The moving of files from a source host to one or more target hosts based on a particular deployment configuration.

deployment configuration

A combination of elements and attribute values which define the criteria for if and how files are to be deployed.


deployment configuration file

An XML-based file that defines the rules and settings for a source host to deploy files to one or more target hosts.

deployment criteria The conditions that indicate whether a file should be deployed as part of a deployment configuration based on particular criteria.

development server A server within the organizational firewall where content is developed and tested prior to being deployed to a production server.

directory comparison

A type of deployment configuration where an area on the source and target hosts are compared with each other, and the differences, based on a set of specified criteria, are deployed to the target host.

EasyDeploy An alternate licensing version of OpenDeploy without certain features, such as fan-out or multi-tiered deployment support, adapter support, and encryption.

edition A TeamSite term for a snapshot of files for the purposes of archiving.

element A logical unit of information within an XML-based document.

encryption The ability to obscure the content of deployments moving between the source and target hosts to prevent unauthorized access.

exception filter A filter used to protect files and directories based on their path or name from any exclusion filters that would otherwise omit them from the deployment.

exclusion filter A filter used to exclude files and directories from a deployment based on their path or name.

fan-out deployment A deployment configuration where the source host simultaneously deploys files to multiple target hosts.

file list deployment A deployment configuration where the source host deploys files to the target hosts based on a predetermined list of files.

filtering Specification of directory paths or file name patterns to include with or exclude from a deployment.

group translation The switching of UNIX-based group ownership on a deployed file or directory between the source host and the target host.

host A server on which one or more OpenDeploy software components reside.

host reporting configuration file

A configuration file residing on each base server or receiver that determines how that host reports events within the reporting environment.

inclusion filter A filter used to include files and directories in a deployment based on their path or name.

information stream A listing of files and directories that are included in a deployment. This data can be streamed to a manifest- or log-based format using Deploy and Run.

instance A particular running of a deployment configuration. An instance name can be appended to the deployment to differentiate it from other occurrences of the same deployment.

495

leg The movement of deployed files from a sending host to a specific target.

log files Files containing information related to the status of the OpenDeploy server or a particular deployment.

log format A legacy format used to organize the information stream data.

logging level One of the choices that determines the amount and type of logged information regarding deployments.

logical host name A name mapped to a host’s name or IP address that is used to identify that host in configurations.

macro deployment log

The log file containing entries related to the activities involving a deployment configuration.

manifest format An XML-based format used to organize the information stream data.

micro deployment log

The log file containing entries related to the activities involving each individual source/target pairing of a deployment.

multi-host installation

The installation of all the required OpenDeploy software components on multiple servers in some combination.

multi-tiered deployment

A deployment configuration where deployed files are received by an OpenDeploy base server host and then redeployed across tiers.

multi-tiered transactional deployment

A multi-tiered deployment in which the deployment transaction spans all servers.

node A host that can send or receive files.

node configuration file

An XML-based configuration file that defines all the target hosts for a source host.

normal logging level A logging level that logs standard status and error messages.

parameter substitution

A special key-value syntax that allows you to specify parameter values when starting or scheduling a deployment. Using this feature, you can specify different values for the same parameter each time you start a deployment.

path An element that further defines a specified file system location or TeamSite area.

path-based filter An inclusion or exclusion filter that compares the path of each file or directory with a specified path to determine whether or not the item can be deployed.

pattern-based filter An inclusion or exclusion filter that compares the name of each file or directory with a specified regular expression to determine whether or not the item can be deployed.

payload adapter-based deployments

Payload adapter-based deployments use a payload adapter in conjunction with OpenDeploy to retrieve files from the source file location based on some selection criteria. Those files that meet the criteria are listed in a generated file manifest.


permission rules Optional directives to apply to the deployed files or directories on the target host.

physical host name The name or IP address of a host.

pre-commit phase A period of time when a transactional deployment determines whether the deployment has been successful and can commit the deployment to all the targets. If the deployment cannot commit, the deployment is rolled back and the target hosts are restored to their previous states.

previous area A second TeamSite area against which the primary area is compared in a TeamSite comparison deployment configuration. The previous area is typically the previous version of the files in the primary area, and also represents the files residing on the target hosts.

primary area The TeamSite area in a TeamSite comparison that contains the most current files. The contents of the primary area are compared with those in the previous area to determine which files are deployable.

production server Typically, a host with content that is accessible either on an intranet or the Internet.

quick report A predefined query that can be accessed and run at any time without any additional report configuration required.

quorum The specified minimum number of successful legs in a transactional deployment for the overall deployment to be considered successful.

receiver A host on which OpenDeploy receiver software is installed. A receiver can only receive deployed files from a source host.

receiver log A log file containing entries related to the receiver host.

receiver macro deployment log

A log generated by the receiving host that contains information for the received deployment.

receiver micro deployment log

A log generated by the receiving host that contains information regarding a specific source/target pairing in a deployment.

recurring deployment

A scheduled deployment where the deployment repeats on a regular basis, such as daily or weekly.

reporting The collection and displaying of deployment information that is managed by the reporting server in a central database.

reporting management configuration file

A configuration file used by the reporting server to subscribe to deployment events from base server and receiver hosts.

reporting server Software that runs the OpenDeploy reporting feature. The reporting server is co-located with the administration server software.

reverse deployment A deployment configuration where files residing on a target host are deployed back to the source host.

reverse source The sender of a reverse deployment.

reverse target The recipient of a reverse deployment.

497

roles The collective term for the Administrator and User roles. The role of an individual user determines what level of features and functionality that person has access to within the OpenDeploy user interface.

rollover threshold The size a log file can grow before it is closed to new entries and archived. A new log file is then generated.

schedule A predetermined time and date when a particular deployment is started. This can occur on a one-time only or recurring basis.

scheduled deployment

A deployment that is performed at a predetermined time and date. A scheduled deployment can occur on a one-time or recurring basis.

scheduler database A database that is installed with the base server software and stores the scheduling information for the source host.

service configuration file

A configuration file located on an OpenDeploy server with the base server or receiver software installed that specifies the name of the base server, receiver, and nodes configuration file being accessed by OpenDeploy. The service configuration file is named deploy.cfg.

simulated deployment

A deployment where no files are moved, but entries are made in the deployment logs for every file or directory that would have been deployed. This feature can be used to determine differences in files on the source and target hosts without actually deploying files.

single-host installation

The installation of all the required OpenDeploy software components on a single server.

source host A host with base server software installed and licensed that can deploy and receive files.

source macro deployment log

A log generated by the sending host that contains information for the sent deployment.

source micro deployment log

A log generated by the sending host that contains information on a specific deployment source/target pairing. If the deployment moves files to multiple target hosts, each source/target pairing will have its own micro deployment log.

SQL query report A method of constructing a free-form report query.

SSL encryption A high level (up to 168-bit) of file encryption you can assign to deployed files, which requires setting up a Secure Sockets Layer (SSL) certificate authority and generating the certificate.

staging area A TeamSite area that receives and stores files submitted to it from the workareas it supports. There is a single staging area for each TeamSite branch.

submit A TeamSite task action where files are moved from a workarea to the staging area.

successful deployment

A deployment that either successfully moved the deployed files to all of its intended targets, or at least to the number of targets specified by the quorum value.

symmetric key encryption

A lower level (40-bit) of encryption you can assign to deployed files.


synchronized deployment

The distribution of file and database assets together using OpenDeploy and DataDeploy in a single deployment transaction.

target host A host with either receiver or base server software installed, which can receive deployed files from a source host.

TeamSite Interwoven content management software.

TeamSite comparison

A deployment configuration where two TeamSite areas are compared on the source host, and the differences are deployed to the specified target hosts. The source host must be configured as a TeamSite server.

test deployment A deployment configuration that comes with OpenDeploy. Using this test determines whether your base server host is properly configured.

tier A grouping of a source host and its target hosts, usually in the context of a multi-tiered deployment.

Tomcat server Software included in the base server software which assists in the generation of the OpenDeploy user interface.

transactional deployment

A feature which restores one or more targets to their previous existing states in the event that the deployment is considered unsuccessful.

transfer rules Optional directives related to moving files from the source host to the target hosts.

user interface The browser-based graphical representation of selected OpenDeploy functions you can use as an alternative to modifying configuration files and entering commands at the command prompt. The user interface provides an easy way to perform OpenDeploy tasks and configurations.

User role A lower level of OpenDeploy access. Users can only start those deployment configurations assigned to them by the administrator.

user translation The switching of UNIX-based user ownership on a deployed file or directory between the source host and the target host.

verbose logging level The highest level of deployment logging; detailed entries are written to the logs as the deployment occurs. This is the default logging level.

workarea A TeamSite area where contributors keep their working files.

499

Index
AACDeploy element 461ACEs
perm bits 198standard perms 199types 198

ACLs 189, 198ignoring vs. preserving 199names 198UNIX deployments 200

action element 129, 449, 455adapters 381

delivery 208, 211, 439logging 269Network Appliance NetCache 444parameter substitution 206payload 471

address attribute 415admin element 449administration server

logging 268reporting 276

Administrator role 71, 73adminurl attribute 449, 459allowBranching attribute 484allowDnrExecution attribute 233allowedDirectories element 28allowedHosts element 28allowMultiLock attribute 484altappdd attribute 450altwlsappdd attribute 450amask attribute 193and element 128append attribute 275application element 454ApplicationGUID attribute 462ApplicationName attribute 462Applications element 462applyExtAttrs attribute 113applySourceFileTime attribute 191appName attribute 449, 455, 459appsvr element 454

Archival module 431ControlHub 432editions, selecting 435installation 432OpenDeploy, standalone 431, 470policies 434scheduled 436

area (areaDiff) attribute 108area (payload) attribute 123area (targetFilesystem) attribute 105, 112area (targetRules) attribute 140area (targetTeamsite) attribute 112area (TeamSite) attribute 110area attribute 94areaDiff element 94, 108areas

alternate target 140file system-based 112TeamSite-based 112

as attribute 227assemblyDLLName attribute 469assemblyName attribute 469AssemblyNameToUninstall element 469async attribute 210, 227asynchronous deployments 70attemptAppDeleteOnDLLDelete attribute 466attribute

currenttime 477keywords 82preservetime 477syntax 81types 81

attributesaddress 415adminurl 449, 459allowBranching 484allowDnrExecution 233allowMultiLock 484altappdd 450altwlsappdd 450amask 193append 275

501

ApplicationGUID 462ApplicationName 462applyExtAttrs 113applySourceFileTime 191appName 449, 455, 459area 94area (areaDiff) 108area (payload) 123area (targetFilesystem) 105, 112area (targetRules) 140area (targetTeamsite) 112area (TeamSite) 110as 227assemblyDLLName 469assemblyName 469async 210, 227attemptAppDeleteOnDLLDelete 466autoResponse 480, 481, 483baseDirectory 459baseProject 483blockCheckInterval 88blockMaxWaitTime 88branch 477bufferSize 196byteIncremental 191cfgPath 272changeAccess 190, 194checksumCompare 188checksumVerify 191class (odAdapter) 210class (payLoadProperties) 124className 285cmd (deploy) 440cmd (rollback) 440cmd (script) 227comment 477, 480commentFile 477compression 191, 192compressionLevel 191, 192ConnectionMode (FTP adapter) 441connectionString 286daily 418date 480, 481dateDifferent 188dateTime 484day (endTime) 419day (startTime) 416debug 294deployment 151

deploymentDir 466description 469directory 193, 251, 264doDeletes 120, 178, 190dontDo 190enabled 272exec (ODMSAppCenterConfig) 461exec (wsadmin) 454exec (xmlaccess) 456, 491execPath (clearcase) 476execPath (pvcs) 483execPath (vss) 480explodedFormat 449file 193filename 454, 456, 491fileNewerThan 484filePath 118fileTimestamp 480, 481fileUseCurrentTime 484followLinks 201force 469format 127from 195From (email adapter) 443fromNode 163gacutilPath 468group 193Host (email adapter) 443Host (FTP adapter) 403, 441host (ftp) 414host (localNode) 86host (odNode) 294host (server) 445host (wsadmin) 454host (xmlaccess) 456, 491hostName 277hostRmiPort 277hour (startTime) 416hourly 418ID 466id 469ignoreAcls 188, 199ignoreGroup 188ignoreModes 188ignoreUser 188instanceName (schedule) 416invokeOnSuccess 151isEventDLL 466isPasswordEncrypted 445


itemPath (clearcaseItem) 478itemPath (pvcsItem) 484itemPath (vssItem) 481key (request) 388keyFile 317, 318label 480, 481level 264loaderClassPath 459localPath 480, 483location (dnrDeployment) 220location (dnrDeploymentJob) 217location (dnrDir) 223location (dnrFile) 222lock 483lockTimeout 446log 478logFile 445logLevel 124, 210mask (dnrDir) 223mask (dnrFile) 222maxAge 446maxBytes 263, 266minAge 446minute (endTime) 420minute (startTime) 416month (endTime) 419month (startTime) 416monthDays 419multiTierTransactional 151, 152name (action) 129, 449, 455name (clearcase) 476Name (COMPLUSApplication) 466name (database) 285name (DLL) 466name (email) 415name (environment) 279name (external) 89, 92name (ftp) 414name (internal) 89name (key) 127name (localNode) 163name (log) 275name (odAdapter) 210name (path) 104name (payLoadProperties) 124name (process) 278name (Property) 466name (property) 286name (pvcs) 483

name (replicationFarm) 90name (routeDefinition) 162name (transportProperties) 196noData 477node 454nologo 469nostage 450noWarn 477obscured (environment) 279obscured (property) 286omask 193operator 126output 480, 481, 483outputfile 491override 484overwrite 477parameter (email) 415parameter (ftp) 414parameter (odAdapter) 210parameter (payLoadProperties) 124parameterNS (custom) 125parameterNS (deploymentConfiguration) 83parameterNS (odAdapter) 210parameters (schedule) 416password (admin) 449password (Credential) 462Password (FTP adapter) 403, 441password (ftp) 414password (load) 459password (pvcsGet) 483password (server) 445password (vssCheckout) 480password (vssGet) 480password (wsadmin) 454password (xmlaccess) 456, 491passwordEncoded 449, 461, 483passwordEncoded (load) 459passwordEncoded (vssCheckout) 480passwordEncoded (vssGet) 481passwordEncoded (wsadmin) 454passwordEncoded (xmlaccess) 456, 491path 275Port (FTP adapter) 441port (odNode) 294port (server) 445port (wsadmin) 454port (xmlaccess) 456, 491preserveAcls 190, 194, 199preserveTime 477

503

previousArea 60, 107, 108, 109, 110, 111projectDB 483projectPath 483promotionGroup 484proxyStubDLL 466publisher 277pwd (wsadmin) 454quorum 148recordExtAttr 114recursive 480, 481, 483regex (exceptPattern) 184regex (excludePattern) 182regex (includePattern) 180rename 477repositoryType 459reserved 477respository 459restartMarker (odReportingConfiguration) 277revert 188revision 484rmReadOnly 191roundRobbin (odReportingConfiguration) 277scheme 469serverClusterFlag 454serverPath 480setAccess 190, 194silent 469sourceAccessibility 449sslCaCertificate 329sslCertificate 329sslCiphers 330sslPrivateKey 329sslVerifyPeer 329stage 450startAppFlag 455startCommand 278startDir 279state (dnrDeployment) 220state (dnrDeploymentJob) 217state (dnrDir) 223state (dnrFile) 222stderr 279stdin 279stopCommand 278stout 279sub-hourly 418Subject (email adapter) 443subPath (exceptPath) 183subPath (excludePath) 181

subPath (includePath) 179svrOrClusterName 454svrTryCount 191svrTryDisableOverwrite 191svrTryInterval 191target 449TargetDir (FTP adapter) 403, 441targetDir (ftp) 414targetFollowLinks 119timeout 87tmpDir (emailSet) 415tmpDir (ftpSet) 414to 195To (email adapter) 443toNode 163transactional 100, 147transactional (opendeploy) 413transactional (routedDeployment) 166triggerPoint 220type 127, 466typeLibrary 466unsubscribed 294useDefinition 147useNode 90, 147User (FTP adapter) 403, 441user (ftp) 414user (permissionRules) 193userconfigfile 449userId 483userid 445userkeyfile 449userName 449userName (load) 459userName (vssCheckout) 480userName (vssGet) 480userName (wsadmin) 454userName (xmlaccess) 456, 491useRouteClass 166useRouteDefinition 166useServerNodeHost 166, 167, 356value (environment) 279value (predicate) 127value (Property) 466value (property) 286version (clearcaseCheckout) 477version (MSCOM) 465version (MSGAC) 468version (ODMSAppCenterConfig) 461version (odNode) 294


version (pvcsGet) 484version (vssCheckout) 480version (vssGet) 481weblogicJar 449webServerName 445weekday 418when (dnrDeployment) 220when (dnrDeploymentJob) 217when (dnrDir) 223when (dnrFile) 222where 227workSpace 483writable 481, 484writableFiles 481writableFiles (vssCheckout) 480year (endTime) 419year (startTime) 416

autoResponse attribute 480, 481, 483

Bbandwidth throttling 196base server

logging 254, 267reporting 272starting 20

base server configuration file 38reporting 272

base server log file 36, 254recovery 267

baseDirectory attribute 459baseProject attribute 483BEA bulk loader adapter

adapter configuration 458BEA bulk loader adapters 458

deployment configuration 460BEA WebLogic 8 adapter 448BEA WebLogic 9 adapter 451BEABulkLoader element 458blockCheckInterval attribute 88blockMaxWaitTime attribute 88bootstrap administrator 32branch attribute 477browsers, refresh 29bufferSize attribute 196byteIncremental attribute 191

CcacheProperties element 446cancellation, deployments 60

certificate authorityexpiration 323setup 321third-party 325

certificatesexpiration 325generation 323verification 327

cfgPath attribute 272changeAccess attribute 190, 194checksumCompare attribute 188checksumVerify attribute 191ciphers 330

default 331high-strength 331low-strength 331no-authentication 331types 331

class (odAdapter) attribute 210class (payLoadProperties) attribute 124className attribute 285clearcase element 476clearcaseCheckout element 477clearcaseItem element 478clearcaseUpdate element 477cmd (deploy) attribute 440cmd (rollback) attribute 440cmd (script) attribute 227command-line tools

iwodauthorize 76iwodcmd archive 437iwodcmd schedactivate 249iwodcmd schedadd 242, 244iwodcmd scheddelete 247iwodcmd schedget 245iwodcmd serverreset 28, 29iwodcmd serverstatus 48iwodcmd start 67, 68iwodnetcache 446iwodnonroot 24iwodservergetversion 47

comment attribute 477, 480commentFile attribute 477comparison rules 187, 375

date-based 189comparisonRules element 187, 188COMPLUS element 462COMPLUSApplication element 466Component element 466

505

Components element 466compression 192compression attribute 191, 192compressionLevel attribute 191, 192concurrency management 88, 344configuration files

base server 38host reporting 273nodes 38receiver 38reporting management 276schedule 425

connection timeout 87, 344ConnectionMode (FTP adapter) attribute 441connectionString attribute 286ContentServices for OpenDeploy 427ControlHub

custom reports 307events database 280

Credential element 462currenttime attribute 477custom element 125custom reports 297

downloading 304exporting to SQL 300generating 300queries 298, 299saving as quick report 305

CVS adapter 485configuration 485

Ddaemons 19

resetting 28daily attribute 418DAS custom reports 305data asset deployments 135, 138

database auto-synchronization 135standalone database 136target-side database deployments 137

database auto-synchronization 135Database Deployment for OpenDeploy Administration

Guide 15database element 285databaseDeployment element 214DataDeploy module 214DataDeploy wrapper files 384date attribute 480, 481dateDifferent attribute 188

dateTime attribute 484day (endTime) attribute 419day (startTime) attribute 416debug attribute 294definition element 93, 146, 147definitions 93, 100

file filters 99file rules 99source file location 93target file location 97types 357

Delivery Adapter Framework 208delivery adapters, writing 211

delivery adapters 208, 211, 439BEA bulk loader 458BEA WebLogic 8 448BEA WebLogic 9 451configuring 210email 442FTP 441generic 439IBM WebSphere 453JDK requirements 212logging 269Microsoft application center 460Microsoft COM+ delivery 464Microsoft global assembly cache provisioning 468sample 213targets 211

delivery element 412Deploy and Run 101, 215, 349

deleting 356deployment-based 220, 354deployment-level triggers 217directory-based 223, 353disabling 233file-based 222, 351macrodeploy triggers 217microdeploy triggers 218package files 233requirements 215reverse deployments 224scripting 227scripts, allowed 229scripts, ordering 230secure invocation 234task-level triggers 218TeamSite comparison 115triggers 216


Windows desktop, interacting 216deploy element 440deployment

authorization checking 68instances 69

deployment attribute 151Deployment Configuration Composer 49, 335

accessing 336comparison rules 375concurrency management 344DataDeploy wrapper files 384definitions 340, 357Deploy and Run 349details 338editing deployments 383encryption 344errors tab 337file naming 342filters 366, 381follow links 371forward deployments 357global deployment settings 339group translation 380log rules 342new configurations 341next-tier deployments 348older configurations 383parameter namespace 342permission rules 378replication farms 347reverse deployments 357saving 382settings 339source file location 358, 361source host name 343target file location 373target host nodes 347targets, alternate 372timeout 344transactional deployments 349transmission rules 376tree tab 337user translation 380

deployment configurationsACLs 198comparison rules 187, 375composing 49creating 341definition 100

definitions 93, 340, 357Deploy and Run 101, 215, 349editing 383encoding 82encryption 344examples 143file naming 82, 342file transport buffer size 196filters 175, 366, 381forward deployments 357group translation 380host specification 86log rules 342logging 67, 142next-tier 348overrides 140, 141parameter namespace 342permission rules 193, 378replication farms 347reverse deployments 357saving 382settings 339source file location 93, 358, 361source host name 343source-based overrides 140structure 83symbolic links 201target file location 97, 373target nodes 347target replication farms 89, 90target-based overrides 141targets, alternate 372tasks 100transactional 100, 349transfer rules 190transmission rules 376uploading 52user translation 380XML code 50, 79

deployment element 100, 146deployment groups 53

access controls 56creating 54directory permissions 55viewing 55

deployment information streamformat 231usage 231

deployment reports 301

507

deploymentConfiguration element 83deploymentDir attribute 466DeploymentName element 462deployments

asynchronous 70authorization 74, 75, 76cancelling 60, 70compare phase 60, 61compression 192data asset 135directory comparison 102exclusions 175extended attributes 114fan-out 146file list 116filtered 175forward 357groups 53instance naming 58instances 206legacy Web sites 144metadata-based 130monitoring 63multi-tiered 149organizing 53package 233parameter substitution 70, 203payload adapter-based 121pre-commit phase 61remote upgrade 385reporting 271reverse 168, 357routed 156running 56, 67scheduled 235scheduling 237simulated 59, 69starting 56, 57, 68, 242TeamSite comparison 107, 112test 59timeout 87transactional 145transfer phase 61types 79, 145, 335

deployNRun element 101, 219deployServerConfiguration element 233description attribute 469directory attribute 193, 251, 264directory comparison 102

EAs, changes 106source file location 102target file location 105TeamSite areas 103time zone differences 106

discrete element 417DLL element 466DLLs element 466dnrDeployment element 220dnrDeploymentJob element 217dnrDir element 220, 223dnrFile element 220, 222documentation, OpenDeploy 13, 15doDeletes attribute 120, 178, 190dontDo attribute 190

EEasyDeploy

fan-out deployments 147multi-tiered deployments 152

elements 80ACDeploy 461action 129, 449, 455admin 449allowedDirectories 28allowedHosts 28and 128application 454Applications 462appsvr 454areaDiff 94, 108AssemblyNameToUninstall 469BEABulkLoader 458cacheProperties 446clearcase 476clearcaseCheckout 477clearcaseItem 478clearcaseUpdate 477comparisonRules 187, 188COMPLUS 462COMPLUSApplication 466Component 466Components 466Credential 462custom 125database 285databaseDeployment 214definition 93, 146, 147delivery 412


deploy 440deployment 100, 146deploymentConfiguration 83DeploymentName 462deployNRun 101, 219deployServerConfiguration 233discrete 417DLL 466DLLs 466dnrDeployment 220dnrDeploymentJob 217dnrDir 220, 223dnrFile 220, 222email 415emailSet 415endTime 419environment 279eventReporting 272exceptPath 183exceptPattern 184excludePath 181excludePattern 182execDeploymentTask 100, 147external 89, 92filelist 94, 118fileSystem 94, 102filters 177frequency 417ftp 414ftpSet 414genericAdapter 440includePath 179, 180internal 89iwStore 94, 108key 127load 459localNode 86, 88, 163, 317, 318, 319, 330log 275logRules 28, 266monthly 419MSAppCenter 461MSCOM 465MSGAC 468name (vss) 480netCacheServerConfiguration 445nextDeployment 151NoACL 462nodeInfo 163NodeName 462

nodeRef 90, 147, 178numericType 127odAdapter 210odAdapterSet 210once 417opendeploy 413or 128path 104, 105, 111pathSpecification 104, 105, 111, 178payload 94, 122payLoadProperties 123payLoadRules 125portal 456, 491predicate 126Properties 466Property 466property 286pvcs 483pvcsGet 483pvcsItem 484query 125ReferenceInfo 469remoteDiff 94, 102replicationFarm 90, 147, 148replicationFarmLink 89, 170replicationFarmSet 90restrictDnr 233reverseSource 170reverseTarget 170rollback 440routedDeployment 166routeDefinition 162schedule 416script 227serverSet 445Source 462source 93, 105, 106sourceFilesystem 97sourceTeamsite 97sourceTransferRules 201startTime 416subscription 411target 93, 97, 106targetFilesystem 112targetRules 140, 178Targets 462targetTeamsite 112, 113taskoptions 455textType 127

509

transferRules 190, 192transportProperties 196userName (Credential) 462vss 480vssCheckout 480vssGet 480vssItem 481websphere 491weekly 418wsadmin 454wscfg 454, 456xmlaccess 456, 491

email adapters 442adapter configuration 443configuration file 443deployment configuration 443

email element 415emailSet element 415enabled attribute 272encryption 344

SSL data transfer 319symmetric key 317types 317

endTime element 419environment element 279eventReporting element 272example deployment configurations 143exception filters 182

compatibility 185file system-based 183, 370pattern-based 184, 370

exceptPath element 183exceptPattern element 184excludePath element 181excludePattern element 182exclusion filters 181


exec (ODMSAppCenterConfig) attribute 461exec (wsadmin) attribute 454exec (xmlaccess) attribute 456, 491execDeploymentTask element 100, 147execPath (clearcase) attribute 476execPath (pvcs) attribute 483execPath (vss) attribute 480explodedFormat attribute 449extended attributes 113

manfist file 114

external element 89, 92

Ffan-out deployments 146

EasyDeploy 147quorum 148transactional 147

file attribute 193file integrity, checking 60file list

directories, auto-generating 118file specification 118UNIX 117Windows 117

file list deployments 116doDeletes option 120file list 118source file location 117symbolic links 119target file location 119

file list differential deployments 472base server configuration 472deployment configuration 472file list, editing 473

file manifestdetermination 161file editing 117

file transport buffer size 196filelist element 94, 118filename attribute 454, 456, 491fileNewerThan attribute 484filePath attribute 118files

base server log 254, 267log 36, 251, 265macro deployment log 256micro deployment log 258receiver log 255receiver macro deployment log 257receiver micro deployment log 261source macro deployment log 256source micro deployment log 259

fileSystem element 94, 102fileTimestamp attribute 480, 481fileUseCurrentTime attribute 484filters 175, 366

combining types 185exception 182, 185, 370exclusion 181, 185, 368, 369


inclusion 179, 185, 367, 368override precedence 178path syntax 185source-side 177source-target interaction 178target-side 177, 381

filters element 177follow links 201

source-side 371target-side 371

followLinks attribute 201force attribute 469format attribute 127frequency element 417From (email adapter) attribute 443from attribute 195fromNode attribute 163FTP adapters 441

adapter configuration 441configuration file 441deployment configuration 442passive mode 441

ftp element 414ftpSet element 414

GgacutilPath attribute 468generic delivery adapters 439

adapter configuration 440deployment configuration 440

genericAdapter element 440group attribute 193group ownership transferal 195group translation 380

HHost (email adapter) attribute 443Host (FTP adapter) attribute 403, 441host (ftp) attribute 414host (localNode) attribute 86host (odNode) attribute 294host (server) attribute 445host (wsadmin) attribute 454host (xmlaccess) attribute 456, 491host reporting configuration file 273

location 275logging 275

hostName attribute 277hostRmiPort attribute 277

hour (endTime) attributeattributes

hour (endTime) 419hour (startTime) attribute 416hourly attribute 418

IIBM Rational ClearCase adapter 475

checkout command 475configuration 475update command 475

IBM WebSphere adapters 453IBM WebSphere Portal adapter 490

configuration 490ID attribute 466id attribute 469ignoreAcls attribute 188, 199ignoreGroup attribute 188ignoreModes attribute 188ignoreUser attribute 188includePath element 179, 180inclusion filters 179


instanceName (schedule) attribute 416instances

naming 58parameter substitution 206specifying 69

Intelligent Delivery module 389internal element 89invokeOnSuccess attribute 151isEventDLL attribute 466isPasswordEncrypted attribute 445itemPath (clearcaseItem) attribute 478itemPath (pvcsItem) attribute 484itemPath (vssItem) attribute 481iwodauthorize 76iwodcmd

offeradd 409offerdelete 423offerget 422subscriptionadd 420subscriptiondelete 423subscriptionget 422

iwodcmd archive 437iwodcmd schedactivate 249iwodcmd schedadd 242, 244

511

iwodcmd scheddelete 247iwodcmd schedget 245iwodcmd serverreset 28, 29iwodcmd serverstatus 48iwodcmd start 67, 68iwodcmd subscriptionschedupdate 425iwodcmd subscriptionsuspend 423iwodnetcache 446iwodnonroot 24

restrictions 27iwodservergetversion 47iwodstart

status codes 68iwStore element 94, 108

Kkey (request) attribute 388key element 127keyFile attribute 317, 318

Llabel attribute 480, 481legacy Web sites, deploying 144level attribute 264load element 459loaderClassPath attribute 459localNode element 86, 88, 163, 317, 318, 319, 330localPath attribute 480, 483location (dnrDeployment) attribute 220location (dnrDeploymentJob) attribute 217location (dnrDir) attribute 223location (dnrFile) attribute 222lock attribute 483lockTimeout attribute 446log attribute 478log element 275log files

archived 266base server 36location 251macro deployment 256manifest 213micro deployment 258monitoring 35permissions 251receiver 36receiver macro deployment 257receiver micro deployment 261recovery 267

size 265source macro deployment 256source micro deployment 259viewing 252

logFile attribute 445logging 251

adapters 269administration server 268base server 254, 264command line 262deployment configurations 142file location 251file permissions 251file size 265hierarchy 264host file recovery 267levels 262, 343macro deployment 67, 256, 265micro deployment 258, 265receiver 255, 264receiver macro deployment 257receiver micro deployment 261recovery 267reporting 275reporting server 277rollover naming 266rollover threshold 265, 342rules 342source macro deployment 256source micro deployment 259SSL encryption 333user interface 262

logging levelsnormal 57, 262, 264, 343verbose 57, 262, 264, 265, 343

login 30first time 32normal 30

logLevel attribute 124, 210logRules element 28, 266

Mmacro deployment logs 67, 256

recovery 267manifest log 213mask (dnrDir) attribute 223mask (dnrFile) attribute 222maxAge attribute 446maxBytes attribute 263, 266


metadata-based deployments 130arbitrary repositories 133other adapters 133TeamSite repositories 131

micro deployment logs 258recovery 267

Microsoft application center adapters 460adapter configuration 460deployment configuration 463

Microsoft COM+ delivery adapters 464adapter configuration 464deployment configuration 467

Microsoft GAC provisioning adaptersadapter configuration 468deployment configuration 469

Microsoft global assembly cache provisioning adapter 468

Microsoft Visual SourceSafe adapter 478checkout command 478configuration 478get command 478

minAge attribute 446minute (endTime) attribute 420minute (startTime) attribute 416MKS Source Integrity adapter 487

configuration 487monitoring 63

completed deployments 66, 67source deployments 66target deployments 66viewing options 64

month (endTime) attribute 419month (startTime) attribute 416monthDays attribute 419monthly element 419MSAppCenter element 461MSCOM element 465MSGAC element 468multi-tiered deployments 149

EasyDeploy 152nextDeployment element 151quorum 153restrictions 153

multiTierTransactional attribute 151, 152

Nname (action) attribute 129, 449, 455name (clearcase) attribute 476Name (COMPLUSApplication) attribute 466

name (database) attribute 285name (DLL) attribute 466name (email) attribute 415name (environment) attribute 279name (external) attribute 89, 92name (ftp) attribute 414name (internal) attribute 89name (key) attribute 127name (localNode) attribute 163name (log) attribute 275name (odAdapter) attribute 210name (path) attribute 104name (payLoadProperties) attribute 124name (process) attribute 278name (Property) attribute 466name (property) attribute 286name (pvcs) attribute 483name (replicationFarm) attribute 90name (routeDefinition) attribute 162name (transportProperties) attribute 196name (vss) element 480NetCache adapters

adapter configuration 445deployment configuration 446internationalization 447

netCacheServerConfiguration element 445Network Appliance NetCache adapters 444nextDeployment element 151next-tier deployments 348NoACL element 462noData attribute 477node attribute 454nodeInfo element 163NodeName element 462nodeRef element 90, 147, 178nodes configuration file 38

target replication farms 92nologo attribute 469non-Administrator, running OpenDeploy as 24non-root

permissions, changing 25running OpenDeploy as 24start up script 26

normal logging level 57, 262, 264, 343nostage attribute 450notation conventions 14noWarn attribute 477numericType element 127

513

Oobscured (environment) attribute 279obscured (property) attribute 286odAdapter element 210odAdapterSet element 210offers 390, 408

customer defined rules 362, 396deleting 399, 423deployment groups 395displaying 422editing 399payload deployment actions 365, 398payload deployments 362, 395processing 409query syntax 363, 396

omask attribute 193once element 417online help 15OpenDeploy

ACLs 198Archival module 431attributes 79, 81comparison rules 187configuration DTDs 79daemons 19DataDeploy module 214delivery adapters 439Deploy and Run 215deployment types 79, 145, 335documentation 13, 15elements 79, 80encryption 317file integrity 60Intelligent Delivery module 389logging 251login 30, 32login options 30monitoring 63non-Administrator, running as 24non-root, running as 24online help 15permission rules 193reconnecting to a restarted server 47refreshing 28reporting 271roles 71schedules 235servers 33services 18, 19, 21, 22

starting 17, 19status 48stopping 21, 23syndication 389transfer rules 190user interface 17, 20, 29, 30version 47Web services 427Web site integrity 60

OpenDeploy Administration Guidenotation conventions 14usage 13

opendeploy element 413OpenDeploy Installation Guide 15OpenDeploy Reference 15OpenDeploy Release Notes 15, 29operator attribute 126or element 128output attribute 480, 481, 483outputfile attribute 491override attribute 484overrides

source-based 140target-based 141

overwrite attribute 477

Ppackage files 233parameter (email) attribute 415parameter (ftp) attribute 414parameter (odAdapter) attribute 210parameter (payLoadProperties) attribute 124parameter substitution 203

adapters 206command-line 205default values 204deployments 70namespace 342namespaces 207scheduled deployments 206, 244user interface 204

parameterNS (custom) attribute 125parameterNS (deploymentConfiguration)

attribute 83parameterNS (odAdapter) attribute 210parameters (schedule) attribute 416password (admin) attribute 449password (Credential) attribute 462Password (FTP adapter) attribute 403, 441


password (ftp) attribute 414password (load) attribute 459password (pvcsGet) attributes 483password (server) attribute 445password (vssCheckout) attribute 480password (vssGet) attribute 480password (wsadmin) attribute 454password (xmlaccess) attribute 456, 491passwordEncoded (load) attribute 459passwordEncoded (vssCheckout) attribute 480passwordEncoded (vssGet) attribute 481passwordEncoded (wsadmin) attribute 454passwordEncoded (xmlaccess) attribute 456, 491passwordEncoded attribute 449, 461, 483path attribute 275path element 104, 105, 111pathSpecification element 104, 105, 111, 178payload adapter-based deployments 121payload adapters 471

CVS 485database 474deployment actions 129file list differential 472IBM Rational ClearCase 475IBM WebSphere Portal 490input, providing 125JDK requirements 471logging 269metadata-based deployments 130Microsoft Visual SourceSafe 478MKS Source Integrity 487PCDATA string 125query syntax 126sample 471Serena PVCS 482software configuration management 475source file location 122specifying 123target file location 123writing 129

payload element 94, 122payLoadProperties element 123payLoadRules element 125permission rules 193, 378

cross-platform 195ownership transferal 195

permissions, file 193Port (FTP adapter) attribute 441port (odNode) attribute 294

port (server) attribute 445port (wsadmin) attribute 454port (xmlaccess) attribute 456, 491portal element 456, 491predicate element 126preserveAcls attribute 190, 194, 199preserveTime attribute 477preservetime attribute 477previousArea attribute 60, 107, 108, 109, 110, 111projectDB attribute 483projectPath attribute 483promotionGroup attribute 484Properties element 466Property element 466property element 286proxyStubDLL attribute 466publisher attribute 277pvcs element 483pvcsGet element 483pvcsItem element 484pwd (wsadmin) attribute 454

Qquery element 125query-based deployments

linked queries 128quick reports 313

list 313, 314SQL query reports 313

quorumfan-out deployments 148multi-tiered deployments 153

quorum attribute 148

Rreceiver

logging 255reporting 272starting 20

receiver configuration file 38reporting 272

receiver log file 36, 255recovery 267

receiver macro deployment log file 257receiver micro deployment log file 261recordExtAttr attribute 114recursive attribute 480, 481, 483ReferenceInfo element 469regex (exceptPattern) attribute 184

515

regex (excludePattern) attribute 182regex (includePattern) attribute 180regular expressions

supported 186use of "^" character 187

remote upgradesdeployments 385progress checking 387remote action requests 386request action 388

remoteDiff element 94, 102rename attribute 477replication farms 347replicationFarm element 90, 147, 148replicationFarmLink element 89, 170replicationFarmSet element 90reporting 271

administration server 276base server 272ControlHub custom reports 307custom reports 297DAS custom reports 305database sizing 316deleting 315enabling 272host configuration 272host reporting configuration file 272logging 275maintenance 315quick reports 313receiver 272servers, adding 294SQL reports 310store-and-forward system 295tables, upgrades 291

reporting management configuration file 276reporting server

configuration file, location 276connection management 277environment variables 279logging 277sub-process commands 278

reporting server database 280configuration 285Hypersonic, resetting 287, 288Hypersonic, upgrading 289name 286password 286resetting 286

upgrading 292using own 280

reportsingdeployment 301

repository attribute 459repositoryType attribute 459reserved attribute 477restartMarker (odReportingConfiguration)

attribute 277restrictDnr element 233reverse deployments 168

configuration 170Deploy and Run 224multiple definitions 170server configuration 169symmetric key encryption 318target replication farms 92

reverseSource element 170reverseTarget element 170revert attribute 188revision attribute 484rmReadOnly attribute 191roles 71

Administrator 71, 73server 73User 72, 73, 74, 75workflows 78

rollback element 440rollover threshold 342

logging 265naming 266size 266

roundRobbin (odReportingConfiguration) attribute 277

route definitions 156, 162, 166route segments 156routed deployments 156, 159, 161

configuration 162, 163configuring 356host checking 167limitations 167manifest information stream 162route definitions 156transactional 356

routedDeployment element 166routeDefinition element 162routeSegments 163rules

comparison 187


permission 193transfer 190

Sschedule configuration file 425schedule element 416scheduled deployments 235

activating 241, 248command line 242comments, use of 244creating 237deactivating 241, 248deleting 241, 247editing 240end-date 244one-time 243parameter substitution 244recurring 244time zones 236user interface 236viewing 239, 245

schedules (syndication) 406, 425changing 407end time 419frequency 417start time 416

scheme attribute 469script element 227scripting, Deploy and Run 227Serena PVCS adapter 482

configuration 482get command 482, 485, 487

server configuration filesuploading 36viewing 38

server element 445server groups 40

configuration files, editing for 43creating 40refreshing 46updating files 44viewing 42

server roles 73access 73

serverClusterFlag attribute 454serverPath attribute 480servers

adding 33changing 34

deleting 35groups 40log files 36managing 33monitoring 35refreshing 38

serverSet element 445services

resetting 28starting 18, 19stopping 21, 22

setAccess attribute 190, 194silent attribute 469simulated deployments 59, 69software configuration management adapters 475

CVS 485IBM Rational ClearCase 475Microsoft Visual SourceSafe 478MKS Source Integrity 487Serena PVCS 482

Source element 462source element 93, 105, 106source file location 93, 358, 361

directory comparison 102file list deployments 117legacy configuration syntax 97modifying files during deployment 97TeamSite comparison 108TeamSite on UNIX 120Windows path naming 99

source hostsarea 104, 111overrides 140

source macro deployment log file 256source micro deployment log file 259sourceAccessibility attribute 449source-based overrides 140sourceFilesystem element 97sourceTeamsite element 97sourceTransferRules element 201SQL reports 310

downloading 312generating 312queries 311, 312quick reports, saving as 313

SSL data transfer encryption 319certificate authority 320, 321certificate generation 323certificate verification 327

517

ciphers 330configuration 329logging 333OpenSSL defaults, changing 326setting up 319SSL errors 326testing 332

sslCaCertificate attribute 329sslCertificate attribute 329sslCiphers attribute 330sslPrivateKey attribute 329sslVerifyPeer attribute 329stage attribute 450standalone database deployments 136startAppFlag attribute 455startCommand attribute 278startDir attribute 279startTime element 416state (dnrDeployment) attribute 220state (dnrDeploymentJob) attribute 217state (dnrDir) attribute 223state (dnrFile) attribute 222stderr attribute 279stdin attribute 279stopCommand attribute 278stout attribute 279sub-hourly attribute 418Subject (email adapter) attribute 443subPath (exceptPath) attribute 183subPath (excludePath) attribute 181subPath (includePath) attribute 179subscription element 411subscriptions 390, 400, 410

activating 424deleting 406, 423delivery methods 402, 412deployment groups 406displaying 422processing 420schedules 406suspending 407, 423updating 425viewing from offer 407

svrOrClusterName attribute 454svrTryCount attribute 191svrTryDisableOverwrite attribute 191svrTryInterval attribute 191symbolic links

target file location 98

symmetric key encryption 317configuration 317reverse deployments 318

synchronized deployments 138syndication 389

activating 424command-line 408deleting files 423delivery methods 412displaying files 422email 415FTP 414offers 390, 391, 408OpenDeploy 413schedules 391, 406, 425subscription updating 425subscriptions 390, 400, 410suspension 423user interface 391Web services 426

Ttarget element 93, 97, 106target file location 97, 373

alternate 140directory comparison 105file list deployments 119mixed platforms 98multiple source deployments 98symbolic link 98TeamSite comparison 112Windows path naming 99

target hostsalternate 140area 141features, defining 142overrides 141root directories 106

target replication farms 89backwards compatibility 90deployment configuration 90location 89multiple references to same host 91nodes configuration file 92reverse deployments 92

target-based overrides 141TargetDir (FTP adapter) attribute 403, 441targetDir (ftp) attribute 414targetFilesystem element 112


targetFollowLinks attribute 119targetRules element 140, 178targets attribute 449Targets element 462target-side database deployments 137targetTeamsite element 112, 113taskoptions element 455TeamSite

extended attributes, deploying 113TeamSite comparison 107

Deploy and Run scripts 115extended attributes, deploying 113legacy Web sites 144previousArea 109source file location 108target file location 112using //IWSERVER 110

test deployments 59textType element 127time zones

directory comparions 106scheduled deployments 236

timeouthost inactivity 87, 344user interface 32

timeout attribute 87tmpDir (emailSet) attribute 415tmpDir (ftpSet) attribute 414To (email adapter) attribute 443to attribute 195toNode attribute 163transactional

routed deployments 356transactional (opendeploy) attribute 413transactional (routedDeployment) attribute 166transactional attribute 100, 147transactional deployments 100, 145, 349

fan-out 147multi-tiered 152routed deployments 161

transfer rules 190transferRules element 190, 192transmission rules 376transportProperties element 196triggerPoint attribute 220type attribute 127, 466typeLibrary attribute 466

Uunspecified routes, resolving 159unsubscribed attribute 294useDefinition attribute 147useName (wsadmin) attribute 454useNode attribute 90, 147User (FTP adapter) attribute 403, 441user (ftp) attribute 414user (permissionRules) attribute 193user interface 29

browser requirements 29login 30scheduled deployments 236servers 33starting 20, 30timeout setting 32

user ownership transferal 195User role 72, 73, 75

access 74user translation 380userconfigfile attribute 449userId attribute 483userid attribute 445userkeyfile attribute 449userName (Credential) element 462userName (load) attribute 459userName (vssCheckout) attribute 480userName (vssGet) attribute 480userName (xmlaccess attribute 456userName (xmlaccess) attribute 491userName attribute 449useRouteClass attribute 166useRouteDefinition attribute 166useServerNodeHost attribute 166, 167, 356

Vvalue (environment) attribute 279value (predicate) attribute 127value (Property) attribute 466value (property) attribute 286verbose logging level 57, 262, 264, 265, 343version (clearcaseCheckout) attribute 477version (MSCOM) attribute 465version (MSGAC) attribute 468version (ODMSAppCenterConfig) attribute 461version (odNode) attribute 294version (pvcsGet) attribute 484version (vssCheckout) attribute 480version (vssGet) attribute 481

519

vss element 480vssCheckout element 480vssGet element 480vssItem element 481

WWeb services 427

syndication 426Web site integrity, checking 60WebLogic 8 adapters

adapter configuration 448deployment configuration 450upload directory 450

WebLogic 9 adaptersadapter configuration 451deployment configuration 451

weblogicJar attribute 449webServerName attribute 445WebSphere adapters

adapter configuration 453application server 454, 457deployment configuration 457portal server 456, 457

websphere element 491weekday attribute 418weekly element 418when (dnrDeployment) attribute 220when (dnrDeploymentJob) attribute 217when (dnrDir) attribute 223when (dnrFile) attribute 222where attribute 227Windows desktop, Deploy and Run 216workSpace attribute 483writable attribute 481, 484writableFiles (vssCheckout) attribute 480writableFiles attribute 481wsadmin element 454wscfg element 454, 456

XXML code 50xmlaccess element 456, 491

Yyear (endTime) attribute 419year (startTime) attribute 416
