open deploy admin strati on guide
TRANSCRIPT
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
6 OpenDeploy Administration Guide
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
8 OpenDeploy Administration Guide
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
10 OpenDeploy Administration Guide
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
12 OpenDeploy Administration Guide
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.
14 OpenDeploy Administration Guide
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
16 OpenDeploy Administration Guide
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
18 OpenDeploy Administration Guide
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.
20 OpenDeploy Administration Guide
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
Base server or receiver
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:
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 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
22 OpenDeploy Administration Guide
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.
24 OpenDeploy Administration Guide
Running OpenDeploy as Non-Administrator or Non-Root
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:
1. Navigate to the following directory:
/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
5. Navigate to the following directory:
/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
7. Navigate to the following directory:
/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
26 OpenDeploy Administration Guide
Running OpenDeploy as Non-Administrator or Non-Root
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:
1. Navigate to the following directory:
od-home/bin
2. Reset the OpenDeploy services by entering the following command at the prompt:
iwodcmd [-odinst instName] serverreset
28 OpenDeploy Administration Guide
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]
OpenDeploy User Interface
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.
30 OpenDeploy Administration Guide
OpenDeploy User Interface
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.
32 OpenDeploy Administration Guide
OpenDeploy Server Management
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.
34 OpenDeploy Administration Guide
OpenDeploy Server Management
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.
36 OpenDeploy Administration Guide
OpenDeploy Server Management
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.
2. Select Servers > Manage Server to display the Server Management window.
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:
1. Select Servers > Manage Server to display the Server Management window.
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.
38 OpenDeploy Administration Guide
OpenDeploy Server Management
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:
1. Select Servers > Manage Server to display the Server Management window.
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
40 OpenDeploy Administration Guide
OpenDeploy Server Management
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).
Figure 11: OpenDeploy Server Groups Window
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).
Figure 12: OpenDeploy Server Groups Window
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:
1. Select Servers > View Server Groups to display the OpenDeploy Server Groups window (Figure 12).
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
42 OpenDeploy Administration Guide
OpenDeploy Server Management
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:
1. Select Servers > View Server Groups to display the OpenDeploy Server Groups window (Figure 12).
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.
44 OpenDeploy Administration Guide
OpenDeploy Server Management
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.
46 OpenDeploy Administration Guide
OpenDeploy Server Management
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:
1. Navigate to the following directory:
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
-h Displays help information.
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:
1. Navigate to the following directory:
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.
-v Displays version information.
-q Omits displaying the number of active deployments.
48 OpenDeploy Administration Guide
Composing 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.
50 OpenDeploy Administration Guide
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:
od-home/(od-instance)/conf
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.
52 OpenDeploy Administration Guide
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.
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. 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.
Organizing Deployment Configurations
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:
od-home/(od-instance)/conf
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.
54 OpenDeploy Administration Guide
Organizing Deployment Configurations
Viewing Deployment Groups
To view your deployment groups and the deployment configurations they contain, follow these steps:
1. Select Configurations > View Configurations to display the Deployment Configuration window (Figure 21).
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
56 OpenDeploy Administration Guide
Running Deployments from the User Interface
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.
58 OpenDeploy Administration Guide
Running Deployments from the User Interface
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.
60 OpenDeploy Administration Guide
Running Deployments from the User Interface
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.
62 OpenDeploy Administration Guide
Monitoring Deployments
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.
64 OpenDeploy Administration Guide
Monitoring Deployments
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.
66 OpenDeploy Administration Guide
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.
Running Deployments from the Command Line
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)]
-h Displays usage information.
-v Displays version information.
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:
1. Navigate to the following directory:
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
68 OpenDeploy Administration Guide
Running Deployments from the Command Line
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
-h Displays usage information.
-v Displays version information.
deployment Name of the deployment to cancel.
70 OpenDeploy Administration Guide
Roles and Authorization
To cancel a deployment in progress from the command line, follow these steps:
1. Navigate to the following directory:
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.
Roles and Authorization
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.
72 OpenDeploy Administration Guide
Roles and Authorization
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
74 OpenDeploy Administration Guide
Roles and Authorization
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.
76 OpenDeploy Administration Guide
Roles and Authorization
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]
-h Displays usage information.
-v Displays version information.
-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.
78 OpenDeploy Administration Guide
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.
80 OpenDeploy Administration Guide
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.
82 OpenDeploy Administration Guide
Deployment Configuration Structure
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>
84 OpenDeploy Administration Guide
Deployment Configuration Structure
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"/>
</deploymentConfiguration>
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"/>...
</deploymentConfiguration>
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.
86 OpenDeploy Administration Guide
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"/>...
</deploymentConfiguration>
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.
88 OpenDeploy Administration Guide
Target Replication Farms
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>...
</replicationFarmLink></target>
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"/>
</replicationFarmLink>
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>...
</deploymentConfiguration>
90 OpenDeploy Administration Guide
Target Replication Farms
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>
</replicationFarm></replicationFarmSet>
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>
</replicationFarm></replicationFarmSet>
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"/>
</replicationFarmLink>
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.
92 OpenDeploy Administration Guide
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>...
</deploymentConfiguration>
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.
94 OpenDeploy Administration Guide
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">
</pathSpecification></remoteDif>
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=".">
</pathSpecification></remoteDif>
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:
<definition name="webfiles"><source><fileSystem>
<remoteDiff area="/dev/website/files">...
</remoteDiff>
<remoteDiff area="/images">...
</remoteDiff></fileSystem>
</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.
96 OpenDeploy Administration Guide
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>
</target></definition>
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.
98 OpenDeploy Administration Guide
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>
100 OpenDeploy Administration Guide
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">...
</execDeploymentTask></deployment>
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>
</fileSystem></source>
/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.
102 OpenDeploy Administration Guide
Directory Comparison Deployments
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>
</remoteDiff></fileSystem>
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"/>
104 OpenDeploy Administration Guide
Directory Comparison Deployments
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"/>
</pathSpecification></remoteDiff>
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>
</remoteDiff></fileSystem>
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>
</fileSystem></source>
<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.
106 OpenDeploy Administration Guide
TeamSite Comparison Deployments
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"
108 OpenDeploy Administration Guide
TeamSite Comparison Deployments
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.
110 OpenDeploy Administration Guide
TeamSite Comparison Deployments
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.
In the following example:
<iwStore><areaDiff area="/default/main/dev/EDITION"previousArea="/default/main/dev/EDITION/IW_PREV"><pathSpecification>
<path name="monthly"/></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>
Defining the Target File Location
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
112 OpenDeploy Administration Guide
TeamSite Comparison Deployments
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
114 OpenDeploy Administration Guide
TeamSite Comparison Deployments
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"?><!-- *** Manifest of Teamsite Extended Attributes --><!-- *** Generated by OpenDeploy -->
<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
116 OpenDeploy Administration Guide
File List Deployments
Defining the Source File Location
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>
</fileSystem></source>
or
<source><iwStore><filelist area="/default/main/dev/EDITION/Jan_04" ...>
...</filelist>
</iwStore></source>
Specifying a Subpath Within the Source File Location
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.
118 OpenDeploy Administration Guide
File List Deployments
Defining the Target File Location
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.
120 OpenDeploy Administration Guide
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
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.
Defining the Source File Location
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>
</fileSystem></source>
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
122 OpenDeploy Administration Guide
Payload Adapter-Based Deployments
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.
Specifying a Subpath Within the Source File Location
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.
124 OpenDeploy Administration Guide
Payload Adapter-Based Deployments
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>...
</payLoadRules></payload>
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” (/=)
126 OpenDeploy Administration Guide
Payload Adapter-Based Deployments
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>
128 OpenDeploy Administration Guide
Payload Adapter-Based Deployments
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"/>
</payLoadRules></payload>
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:
od-home/(od-instance)/userlib
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
130 OpenDeploy Administration Guide
Payload Adapter-Based Deployments
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"/>
</payLoadProperties>
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>...
</payLoadRules></payload>
</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.
132 OpenDeploy Administration Guide
Payload Adapter-Based Deployments
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>...
</payLoadRules></payload>
</fileSystem></source>
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.
134 OpenDeploy Administration Guide
Data Asset Deployments
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
136 OpenDeploy Administration Guide
Data Asset Deployments
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.
138 OpenDeploy Administration Guide
Data Asset Deployments
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.
Code and content files are deployed to target.
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"/>
</pathSpecification></remoteDiff>
</fileSystem></source>
<target><targetFilesystem area="D:\website\files">
<replicationFarmLink><internal name="web_farm"/>
</replicationFarmLink></target>
140 OpenDeploy Administration Guide
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>
</replicationFarm></replicationFarmSet>
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.
142 OpenDeploy Administration Guide
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.
144 OpenDeploy Administration Guide
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
Content Delivery Methods
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.
146 OpenDeploy Administration Guide
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
Content Delivery Methods
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.
OpenDeploy references a fan-out deployment configuration.
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.
148 OpenDeploy Administration Guide
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.
Multi-Tiered Deployments
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.
OpenDeploy references a fan-out deployment configuration.
mars
venus
jupiter
mercury
Files are deployed to targets.
quorum=2transactional=yes
149
Content Delivery Methods
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.
150 OpenDeploy Administration Guide
Multi-Tiered Deployments
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
Content Delivery Methods
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.
152 OpenDeploy Administration Guide
Multi-Tiered Deployments
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
Content Delivery Methods
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>
</replicationFarm></replicationFarmSet>
<definition name="def1"><source>
<fileSystem><remoteDiff area="/dev/accounting/reports">
<pathSpecification><path name="."/>
</pathSpecification></remoteDiff>
</fileSystem></source><target>
<targetFilesystem area="/dev/external/reports"/><replicationFarmLink><internal name="reports"/>
</replicationFarmLink>
</target></definition>
<definition name="def2"><source>
<fileSystem><remoteDiff area="/dev/finance/reports">
<pathSpecification><path name="."/>
</pathSpecification></remoteDiff>
</fileSystem></source><target>
<targetFilesystem area="/dev/internal/reports"/><replicationFarmLink><internal name="reports"/>
</replicationFarmLink></target>
</definition>...
</deploymentConfiguration>
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.
154 OpenDeploy Administration Guide
Multi-Tiered Deployments
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>
</replicationFarm></replicationFarmSet>
<definition name="def1"><source>
<fileSystem><remoteDiff area="/dev/accounting/reports">
...</remoteDiff><remoteDiff area="/dev/finance/reports">
<pathSpecification><path name="."/><targetRules area="/dev/internal/reports"/>
</pathSpecification></remoteDiff>
</fileSystem></source><target>
<targetFilesystem area="/dev/external/reports"/><replicationFarmLink><internal name="reports"/>
</replicationFarmLink></target>
</definition>...
</deploymentConfiguration>
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
Content Delivery Methods
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
156 OpenDeploy Administration Guide
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
mercury —> jupiter
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
Content Delivery Methods
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
mercury —> jupiter
mars —> venus
venus —> jupiter
jupiter —> saturn
jupiter —> pluto
158 OpenDeploy Administration Guide
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
Content Delivery Methods
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
160 OpenDeploy Administration Guide
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
Content Delivery Methods
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">...
</routesDefinition></nodeSet>
162 OpenDeploy Administration Guide
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"/>
</routesDefinition></nodeSet>
You can specify a regular expression as the value for the toNode attribute. For example:
<nodeInfo fromNode="england" toNode="london.*"/>
163
Content Delivery Methods
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">...
</routesDefinition></nodeSet>
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.
164 OpenDeploy Administration Guide
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
Content Delivery Methods
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.
166 OpenDeploy Administration Guide
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
Content Delivery Methods
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.
168 OpenDeploy Administration Guide
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
Files are reverse deployed back to the reverse target.
Base server initiates reverse deployment to reverse source.
169
Content Delivery Methods
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.
170 OpenDeploy Administration Guide
Certified Limits for Number of Deployment Legs
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:
od-home/(od-instance)/conf
For OpenDeploy running on a Solaris host, the name server cache daemon (NSCD) was enabled.
171
Content Delivery Methods
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)
172 OpenDeploy Administration Guide
Certified Limits for Number of Deployment Legs
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"/>
</pathSpecification></remoteDiff>
</fileSystem></source><target><targetFilesystem area="__ignored__"/><replicationFarmLink>
<internal name="WEBSERVERS"/></replicationFarmLink>
</target></definition>
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
Content Delivery Methods
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>
</remoteDiff></fileSystem>
</source><target><targetFilesystem area="/targetarea1"/><replicationFarmLink>
<internal name="WEBSERVERS"/></replicationFarmLink>
</target></definition><definition name="def2">
<source><fileSystem>
<remoteDiff area="/area2"><pathSpecification>
<path name="bbb"/></pathSpecification>
</fileSystem></source><target><targetFilesystem area="/targetarea2"/><replicationFarmLink>
<internal name="WEBSERVERS"/></replicationFarmLink>
</target></definition>
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).
174 OpenDeploy Administration Guide
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.
176 OpenDeploy Administration Guide
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>...
</pathSpecification></remoteDiff>
</fileSystem></source>
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>
</pathSpecification></remoteDiff>
</fileSystem></source>
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>
</replicationFarm></replicationFarmSet>
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.
178 OpenDeploy Administration Guide
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$"
180 OpenDeploy Administration Guide
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.
182 OpenDeploy Administration Guide
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.
In the following example:
<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$"/>
In the following example:
<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.
184 OpenDeploy Administration Guide
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.
186 OpenDeploy Administration Guide
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:
188 OpenDeploy Administration Guide
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.
190 OpenDeploy Administration Guide
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"/>
OpenDeploy applies the following rules:
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.
192 OpenDeploy Administration Guide
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.
In the following example:
<permissionRulesdirectory="770"file="664"group="marketing"user="rroe"/>
OpenDeploy applies the following rules:
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.
194 OpenDeploy Administration Guide
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
In the following example:
<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"/>...
</deploymentConfiguration>
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.
196 OpenDeploy Administration Guide
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
198 OpenDeploy Administration Guide
Using OpenDeploy with ACLs
Standard Perms
Standard perms consists of one of the following:
ALL — RWXDPO
NONE — none
READ — RX
WRITE — W
CHANGE — RWXD
In the following example:
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.
In the following example:
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.
200 OpenDeploy Administration Guide
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.
202 OpenDeploy Administration Guide
Parameter Substitution
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
204 OpenDeploy Administration Guide
Parameter Substitution
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.
206 OpenDeploy Administration Guide
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.
208 OpenDeploy Administration Guide
Utilizing the Delivery Adapter Framework
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.
210 OpenDeploy Administration Guide
Utilizing the Delivery Adapter Framework
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:
od-home/(od-instance)/userlib
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.
212 OpenDeploy Administration Guide
Utilizing the Delivery Adapter Framework
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.
214 OpenDeploy Administration Guide
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:
1. Open the Services window. This process may differ depending on which version of Windows you are using.
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
216 OpenDeploy Administration Guide
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">
yes Deployment runs regardless, and returns status Completed and code 0.no
218 OpenDeploy Administration Guide
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>...
</target></definition>
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>
</execDeploymentTask></deployment>
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>
</execDeploymentTask></deployment>
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.
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.
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.
220 OpenDeploy Administration Guide
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.
In the following example:
<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.
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.
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.
In the following example:
mask=".*\.html$"
222 OpenDeploy Administration Guide
Triggers
any file with the file extension .html in the specified path will trigger the script defined within the Deploy and Run configuration.
In the following example:
<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.
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.
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.
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
In the following example:
mask="cgi-bin$"
any directory named cgi-bin that is deployed will trigger the script.
In the following example:
<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
Files are reverse deployed back to the reverse target.
Base server host initiates reverse deployment to reverse source.
224 OpenDeploy Administration Guide
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.
Configuration Transactional Response Code Behavior
<dnrDeploymentlocation="source"when="before"triggerPoint="connect">
yes Deployment runs regardless, and returns status Completed and code 0.no
<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">
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="after"triggerPoint="disconnect">
yes Deployment runs regardless, and returns status Completed and code 0.no
<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.
yes Deployment rolls back, and returns status Failed and code 2.
no Deployment is aborted, and returns status Failed and code 2.
<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.
no Deployment is aborted midstream, and returns status Completed with Errors and code 9.
<dnrDirlocation="target"when="before">
yes Not supported.
no Deployment is aborted midstream, and returns status Completed with Errors and code 9.
<dnrDirlocation="target"when="after">
yes Not supported.
no Deployment is aborted midstream, and returns status Completed with Errors and code 9.
Configuration Transactional Response Code Behavior
226 OpenDeploy Administration Guide
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
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
In the following example:
<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.
228 OpenDeploy Administration Guide
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.
<definition name="webfiles"><source><fileSystem>
<remoteDiff area="/website/files"><pathSpecification>
<path name="monthly"/></pathSpecification>
</remoteDiff></fileSystem>
</source><target><targetFilesystem area="/website/files"/>
<replicationFarmLink><internal name="WebServers"/>
</replicationFarmLink></target>
</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
230 OpenDeploy Administration Guide
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.
232 OpenDeploy Administration Guide
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.
234 OpenDeploy Administration Guide
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
Scheduled Deployments
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.
236 OpenDeploy Administration Guide
Scheduling from the User Interface
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
Scheduled Deployments
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.
238 OpenDeploy Administration Guide
Scheduling from the User Interface
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
Scheduled Deployments
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 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:
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 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.
240 OpenDeploy Administration Guide
Scheduling from the User Interface
Deleting Scheduled Deployments
To delete a scheduled deployment, 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 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 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:
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 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 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
Scheduled Deployments
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:
1. Navigate to the following directory:
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"]+
-h Displays help information.
-v Displays version information.
-odinst instName Uses OpenDeploy instance instName.
deployment Name of the deployment being scheduled.
242 OpenDeploy Administration Guide
Scheduling from the Command Line
-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
Scheduled Deployments
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^"
244 OpenDeploy Administration Guide
Scheduling from the Command Line
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:
1. Navigate to the following directory:
od-home/bin
245
Scheduled Deployments
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
-h Displays usage information.
-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
246 OpenDeploy Administration Guide
Scheduling from the Command Line
Deleting a Schedule
To delete a schedule using the command line, follow these steps:
1. Navigate to the following directory:
od-home/bin
2. Delete a schedule from a deployment by entering the following command at the prompt:
iwodcmd [-odinst instName] scheddelete deployment options
where deployment is the name of the deployment.
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]
-h Displays usage information.
-v Displays version information.
-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
Scheduled Deployments
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:
1. Navigate to the following directory:
od-home/bin
2. Activate or deactivate a scheduled deployment by entering the following command at the prompt:
iwodcmd [-odinst instName] schedactivate deployment options
where deployment is the name of the deployment.
248 OpenDeploy Administration Guide
Scheduling from the Command Line
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]
-h Displays usage information.
-v Displays version information.
-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
Scheduled Deployments
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.
250 OpenDeploy Administration Guide
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.
252 OpenDeploy Administration Guide
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.
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.
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
254 OpenDeploy Administration Guide
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
256 OpenDeploy Administration Guide
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
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 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
258 OpenDeploy Administration Guide
Micro Deployment Logging
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
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.
source-server — the name of the source sending the deployment.
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
260 OpenDeploy Administration Guide
Micro Deployment Logging
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
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.
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 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.
262 OpenDeploy Administration Guide
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
264 OpenDeploy Administration Guide
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.
266 OpenDeploy Administration Guide
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.
268 OpenDeploy Administration Guide
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
270 OpenDeploy Administration Guide
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
Server Configuration
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.
272 OpenDeploy Administration Guide
Server Configuration
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"><!-- OpenJMS 0.7.6.1 --><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>
274 OpenDeploy Administration Guide
Server Configuration
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>
<!-- Repeat the odNode element for each OD base/receiver being subscribed to --> <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.
276 OpenDeploy Administration Guide
Administration Server Configuration for Reporting
Connection Management
The odReportingConfiguration element is the root element of the reporting management configuration file.
<odReportingConfiguration hostName="saturn" restartInterval="150000"roundRobbin="true">...
</odReportingConfiguration>
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"/>...
</odReportingConfiguration>
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...
</odReportingConfiguration>
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.
278 OpenDeploy Administration Guide
Administration Server Configuration for Reporting
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.
280 OpenDeploy Administration Guide
Administration Server Configuration for Reporting
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:
admin-home/odadmin/config
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:
<!-- Uncomment for using IBM DB2 database. Replace the parameters.<database name="ReportingDB"
className="COM.ibm.db2.jdbc.net.DB2Driver"connectionString="jdbc:db2://DBHOSTNAME:DBPORT/REPORTDBNAME"><property name="user" value="USERNAME"/><property name="password" value="PASSWD"/>
</database>
-->
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.
6. Save and close the file.
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
282 OpenDeploy Administration Guide
Administration Server Configuration for Reporting
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:
iw-home/tsreport/conf
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.
10. Save and close the file.
11. Enter the following command at the prompt:
Windows — alldbschema.bat
UNIX — alldbschema.sh
12. Open the reporting management configuration file (adminEventReportingConfig.xml) file, which resides in the following location:
admin-home/odadmin/config
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:
<!-- Uncomment for using IBM DB2 database. Replace the parameters.<database name="ReportingDB"
className="COM.ibm.db2.jdbc.net.DB2Driver"connectionString="jdbc:db2://DBHOSTNAME:DBPORT/REPORTDBNAME"><property name="user" value="USERNAME"/><property name="password" value="PASSWD"/>
</database>
-->
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.
15. Save and close the file.
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.
18. Navigate to the following location:
admin-home/odadmin/db
284 OpenDeploy Administration Guide
Administration Server Configuration for Reporting
19. Enter the following command at the prompt:
Windows — iwoddbtool.bat -sql ODEvents_DBMS.sql
UNIX — ./iwoddbtool -sql ODEvents_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.
20. 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.
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.
286 OpenDeploy Administration Guide
Administration Server Configuration for Reporting
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.
2. Navigate to the following location:
admin-home/odadmin/db
3. Delete the eventReporting.db.* files.
4. Enter the following command at the prompt:
Windows — iwoddbtool.bat -sql ODEvents_hSql.sql
UNIX — ./iwoddbtool -sql ODEvents_hSql.sql
5. Enter the following command at the prompt:
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:
iw-home/tsreport/conf
7. Rename the tsreport.xml.example file, which resides in the following location:
iw-home/tsreport/conf
to tsreport.xml.
8. Navigate to the following location:
iw-home/tsreport
9. Rename the following file to a name of your own choosing, keeping the .bat or .sh extension intact:
Windows — alldbschema.bat
UNIX — alldbschema.sh
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
288 OpenDeploy Administration Guide
Administration Server Configuration for Reporting
[DBUSER] — SA
[DBPASSWORD] — (leave blank)
[DBSERVER] — controlhub
[DBNAME] — (leave blank)
[DBPORT] — 9001
11. Save and close the file.
12. Enter the renamed .bat or .sh file at the prompt.
13. Navigate to the following location:
admin-home/odadmin/db
14. Enter the following command at the prompt:
Windows — iwoddbtool.bat -sql ODEvents_hSql.sql
UNIX — ./iwoddbtool -sql ODEvents_hSql.sql
15. Enter the following command at the prompt:
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
3. Enter the following command at the prompt:
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.
2. Navigate to the following location:admin-home/odadmin/db
3. Enter the following command at the prompt:
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.
290 OpenDeploy Administration Guide
Administration Server Configuration for Reporting
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 -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
3. Enter the following commands at the prompt:
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:
1. Stop the administration server. See “Stopping OpenDeploy” on page 21 for more information.
2. Navigate to the following location:
admin-home/odadmin/db
3. Enter the following commands at the prompt:
rm eventReporting.db.*
./iwoddbtool -sql ODEvents_hSql.sql
./iwoddbtool -sql quickreportlist_hSql.sql
292 OpenDeploy Administration Guide
Administration Server Configuration for Reporting
Upgrading on Windows
To upgrade your legacy Hypersonic reporting database to the current release 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
3. Enter the following commands 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
Upgrading on UNIX
To upgrade your legacy Hypersonic reporting database to the current release on UNIX, follow these steps:
1. Stop the administration server. See “Stopping OpenDeploy” on page 21 for more information.
2. Navigate to the following location:
admin-home/odadmin/db
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"/>
</odReportingConfiguration>
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"/>
</odReportingConfiguration>
294 OpenDeploy Administration Guide
Administration Server Configuration for Reporting
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.
296 OpenDeploy Administration Guide
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
298 OpenDeploy Administration Guide
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.
300 OpenDeploy Administration Guide
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
302 OpenDeploy Administration Guide
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.
304 OpenDeploy Administration Guide
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.
306 OpenDeploy Administration Guide
ControlHub Custom Reports
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)
308 OpenDeploy Administration Guide
ControlHub Custom Reports
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.
310 OpenDeploy Administration Guide
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.
312 OpenDeploy Administration Guide
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.
314 OpenDeploy Administration Guide
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
316 OpenDeploy Administration Guide
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:
<localNode host="mars" keyFile="/local/OpenDeploy/conf/keyfile.txt"/>
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:
<localNode host="mars" keyFile="/local/OpenDeploy/conf/keyfile.txt"/>
318 OpenDeploy Administration Guide
Secure Data Transfer with SSL
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
320 OpenDeploy Administration Guide
Secure Data Transfer with SSL
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.
2. Navigate to the following location:
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.
8. Save and close the file.
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.
322 OpenDeploy Administration Guide
Secure Data Transfer with SSL
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.
324 OpenDeploy Administration Guide
Secure Data Transfer with SSL
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.
326 OpenDeploy Administration Guide
Secure Data Transfer with SSL
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.
328 OpenDeploy Administration Guide
Secure Data Transfer with SSL
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.
330 OpenDeploy Administration Guide
Secure Data Transfer with SSL
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:
1. Navigate to the following location:
od-home/(od-instance)/conf
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.
332 OpenDeploy Administration Guide
Secure Data Transfer with SSL
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.
334 OpenDeploy Administration Guide
Chapter 10
Composing Deployments
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
Composing Deployments
To access the Deployment Configuration Composer, follow these steps:
1. Select Configurations > View Configurations to display the Deployment Configuration window (Figure 1).
Figure 1: Deployment Configuration Window
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 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.
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.
336 OpenDeploy Administration Guide
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
Composing Deployments
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.
338 OpenDeploy Administration Guide
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
Composing Deployments
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.
340 OpenDeploy Administration Guide
Creating a New Configuration
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.
Figure 4: Deployment Configuration Window
341
Composing Deployments
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
342 OpenDeploy Administration Guide
Creating a New Configuration
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
Composing Deployments
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.
344 OpenDeploy Administration Guide
Creating a New Configuration
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
Composing Deployments
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.
346 OpenDeploy Administration Guide
Creating a New Configuration
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
Composing Deployments
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.
348 OpenDeploy Administration Guide
Creating a New Configuration
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
Composing Deployments
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
350 OpenDeploy Administration Guide
Creating a New Configuration
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
Composing Deployments
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
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.
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.
352 OpenDeploy Administration Guide
Creating a New Configuration
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.
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.
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.
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
353
Composing Deployments
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
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.
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 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.
354 OpenDeploy Administration Guide
Creating a New Configuration
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.
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.
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
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.
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.
355
Composing Deployments
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.
356 OpenDeploy Administration Guide
Creating a New Configuration
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
Composing Deployments
Select the type of definition you want from the Definition Type list.
Defining the Source File Location
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.
358 OpenDeploy Administration Guide
Creating a New Configuration
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
Composing Deployments
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:
• Area — specify the full path to the source file system location or TeamSite area.
• 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.
360 OpenDeploy Administration Guide
Creating a New Configuration
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
Composing Deployments
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.
362 OpenDeploy Administration Guide
Creating a New Configuration
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.
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.
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
Composing Deployments
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
364 OpenDeploy Administration Guide
Creating a New Configuration
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
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
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.
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.
365
Composing Deployments
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.
366 OpenDeploy Administration Guide
Creating a New Configuration
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
Composing Deployments
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
368 OpenDeploy Administration Guide
Creating a New Configuration
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$
See “Supported Regular Expressions” on page 186 for more information on using regular expressions in deployment configurations.
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
Composing Deployments
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
370 OpenDeploy Administration Guide
Creating a New Configuration
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$
See “Supported Regular Expressions” on page 186 for more information on using regular expressions in deployment configurations.
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
Composing Deployments
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.
372 OpenDeploy Administration Guide
Creating a New Configuration
Defining the Target File Location
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
Composing Deployments
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.
374 OpenDeploy Administration Guide
Creating a New Configuration
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
Composing Deployments
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.
376 OpenDeploy Administration Guide
Creating a New Configuration
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
Composing Deployments
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--).
378 OpenDeploy Administration Guide
Creating a New Configuration
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
Composing Deployments
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
380 OpenDeploy Administration Guide
Creating a New Configuration
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
Composing Deployments
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
382 OpenDeploy Administration Guide
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
Composing Deployments
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
384 OpenDeploy Administration Guide
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
Editing Remote Upgrade Deployments
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
Composing Deployments
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.
386 OpenDeploy Administration Guide
Editing Remote Upgrade Deployments
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
Composing Deployments
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.
388 OpenDeploy Administration Guide
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.
390 OpenDeploy Administration Guide
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).
Figure 2: Offer Window
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.
392 OpenDeploy Administration Guide
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:
• Area — specify the full path to the source file system location or TeamSite area.
FileList:
• Area — specify the full path to the source file system location or TeamSite area.
• 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
394 OpenDeploy Administration Guide
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.
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.
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.
396 OpenDeploy Administration Guide
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
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
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.
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.
398 OpenDeploy Administration Guide
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.
400 OpenDeploy Administration Guide
User Interface
5. Click Offer: Edit to display the Offer window (Figure 18).
Figure 18: Offer Window
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.
402 OpenDeploy Administration Guide
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.
Log Rules button — click to configure deployment logging.
Local Node button — click to specify the sending host, and to configure encryption.
Permission Rules button — click to define the rules applicable to the permissions of deployed files and directories
Deploy and Run button — click to assign and configure Deploy and Run scripts to the deployment.
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.
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.
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.
Log Rules button — click to configure deployment logging.
Local Node button — click to specify the sending host, and to configure encryption.
Deploy and Run button — click to assign and configure Deploy and Run scripts to the deployment.
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.
404 OpenDeploy Administration Guide
User Interface
email Address box — enter the email address of the recipient.
Delete button — click to delete the associated email entry.
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.
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.
406 OpenDeploy Administration Guide
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>
</query></payLoadRules>
</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.
408 OpenDeploy Administration Guide
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:
1. Navigate to the following directory:
od-home/bin
2. Enter the following command at the prompt:
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.
410 OpenDeploy Administration Guide
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">
<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"/></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.
412 OpenDeploy Administration Guide
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"/>
</replicationFarmLink></target>
</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.
logRules — see Chapter 7, “Logging” on page 251.
localNode — see “Specifying the Deployment Host” on page 86.
permissionRules — see “Permission Rules” on page 193.
dnrDeploymentJob — see Chapter 5, “Deploy and Run” on page 215.
deployNRun — see Chapter 5, “Deploy and Run” on page 215.
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.
414 OpenDeploy Administration Guide
Command-Line
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.
logRules — see Chapter 7, “Logging” on page 251.
localNode — see “Specifying the Deployment Host” on page 86.
dnrDeploymentJob — see Chapter 5, “Deploy and Run” on page 215.
deployNRun — see Chapter 5, “Deploy and Run” on page 215.
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"/>
416 OpenDeploy Administration Guide
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/>
</type><endTime ... />
<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>
418 OpenDeploy Administration Guide
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>...
</type><endTime ... />
<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:
1. Navigate to the following directory:
od-home/bin
2. Enter the following command at the prompt:
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
420 OpenDeploy Administration Guide
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">
<nodeRef useNode="MyLocalHost"/></replicationFarm>
</replicationFarmSet><definition name="MYDEFINITIONNAME"><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>
</query></payLoadRules>
</payload></iwStore>
</source><target>
<targetFilesystem area="/var/tmp/odtest"/><comparisonRules dateDifferent="yes"/><transferRules doDeletes="yes"/><permissionRules directory="0755" file="0644"/><replicationFarmLink><internal name="MYFARMNAME"/>
</replicationFarmLink></target>
</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:
1. Navigate to the following directory:
od-home/bin
2. Enter the following command at the prompt:
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:
1. Navigate to the following directory:
od-home/bin
2. Enter the following command at the prompt:
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.
422 OpenDeploy Administration Guide
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:
1. Navigate to the following directory:
od-home/bin
2. Enter the following command at the prompt:
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:
1. Navigate to the following directory:
od-home/bin
2. Enter the following command at the prompt:
iwodcmd [-odinst instName] subscriptiondelete -s subscriptionName
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 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:
1. Navigate to the following directory:
od-home/bin
2. Enter the following command at the prompt:
iwodcmd [-odinst instName] subscriptionsuspend -s subscriptionName
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 subscription name.
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:
1. Navigate to the following directory:
od-home/bin
2. Enter the following command at the prompt:
iwodcmd [-odinst instName] subscriptionactivate -s subscriptionName
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 subscription name.
424 OpenDeploy Administration Guide
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:
1. Navigate to the following directory:
od-home/bin
2. Enter the following command at the prompt:
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.
426 OpenDeploy Administration Guide
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
Base server or receiver
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
428 OpenDeploy Administration Guide
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
430 OpenDeploy Administration Guide
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
432 OpenDeploy Administration Guide
Archiving with ControlHub
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.
434 OpenDeploy Administration Guide
Archiving with ControlHub
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.
436 OpenDeploy Administration Guide
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]
-h Displays usage information.
-v Displays version information.
-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
438 OpenDeploy Administration Guide
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
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.
Deployment Configuration
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.
440 OpenDeploy Administration Guide
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.
Adapter Configuration
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
Deployment Configuration
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.
442 OpenDeploy Administration Guide
Email Adapter
Adapter Configuration
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
Deployment Configuration
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.
2. Add the following elements and attributes within the target element:<odAdapterSet>
<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
444 OpenDeploy Administration Guide
Network Appliance NetCache Adapter
Adapter Configuration
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.
The following is an example of this configuration file:
<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.
Deployment Configuration
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
-h Displays help information.
-v Displays version information.
-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.
446 OpenDeploy Administration Guide
Network Appliance NetCache Adapter
-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.
Adapter Configuration
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.
The following is an example of this configuration file:
<!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
448 OpenDeploy Administration Guide
BEA WebLogic 8 Adapter
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).
Deployment Configuration
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:
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:<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.
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.
450 OpenDeploy Administration Guide
BEA WebLogic 9 Adapter
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.
BEA WebLogic 9 Adapter
OpenDeploy includes a delivery adapter that supports application provisioning in archive or exploded format to BEA Systems WebLogic 9 application servers.
Adapter Configuration
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.
The following is an example of this configuration file:
<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
Deployment Configuration
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:
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.
451
Delivery Adapters
2. Add the following elements and attributes within the target element:
<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
452 OpenDeploy Administration Guide
IBM WebSphere Adapters
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.
Adapter Configuration
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
Note the use of three slashes (“///”).
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.
454 OpenDeploy Administration Guide
IBM WebSphere Adapters
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:
<!DOCTYPE websphere SYSTEM "file:///od-home/adapters/delivery/appserver/websphere/dtd/WebSphereAppServer.dtd">
<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
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
Note the use of three slashes (“///”).
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.
456 OpenDeploy Administration Guide
IBM WebSphere Adapters
Deployment Configuration
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:
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="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.
Adapter Configuration
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.
The following is an example of this configuration file:
<!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
Note the use of three slashes (“///”).
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.
458 OpenDeploy Administration Guide
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.
password — specify the password associated with the user name.
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
Deployment Configuration
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:
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:<odAdapterSet>
<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.
Adapter Configuration
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.
460 OpenDeploy Administration Guide
Microsoft Application Center Adapter
The following is an example of this configuration file:
<!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
Note the use of three slashes (“///”).
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
462 OpenDeploy Administration Guide
Microsoft Application Center Adapter
Deployment Configuration
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:
od-home/adapters/delivery/ms/conf
To configure your deployment to use the Microsoft Application Center 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:
<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.
Adapter Configuration
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.
The following is an example of this configuration file:
<!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}" ProgID="Shipping.Cmd"> -->
<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}" ProgID="Shipping.Info"> -->
<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;
464 OpenDeploy Administration Guide
Microsoft COM+ Adapter
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="{BA4F38E0-1AA3-4964-BE61-2AA5E0C56D60}" ProgID="Shipping.Delivery"> -->
<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"/>
<Property name="MinPoolSize" value="1" type="Long"/><Property name="MaxPoolSize" value="1" type="Long"/><Property name="CreationTimeout" value="2147483600"type="Long"/>
</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
Note the use of three slashes (“///”).
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.
466 OpenDeploy Administration Guide
Microsoft COM+ Adapter
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"/>
Deployment Configuration
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:
od-home/adapters/delivery/ms/conf
To configure your deployment to use the Microsoft COM+ 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.
2. Add the following elements and attributes within the target element:
<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.
Adapter Configuration
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.
The following is an example of this configuration file:
<!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
Note the use of three slashes (“///”).
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.
468 OpenDeploy Administration Guide
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.
Deployment Configuration
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:
od-home/adapters/delivery/ms/conf
To configure your deployment to use the Microsoft GAC 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.
469
Delivery Adapters
2. Add the following elements and attributes within the target element:
<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.
470 OpenDeploy Administration Guide
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"/>
</payLoadRules></payload>
See “Specifying the Payload Adapter” on page 123 for more information.
472 OpenDeploy Administration Guide
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"/>
</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 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.
password — specify the password associated with the user name.
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.
474 OpenDeploy Administration Guide
Software Configuration Management Adapters
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”/>
See “Specifying the Payload Adapter” on page 123 for more information.
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.
Adapter Configuration
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">
Note the use of three slashes (“///”).
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.
476 OpenDeploy Administration Guide
Software Configuration Management Adapters
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”/>
See “Specifying the Payload Adapter” on page 123 for more information.
Adapter Configuration
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
478 OpenDeploy Administration Guide
Software Configuration Management Adapters
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">
Note the use of three slashes (“///”).
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.
480 OpenDeploy Administration Guide
Software Configuration Management Adapters
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:
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 (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”/>
See “Specifying the Payload Adapter” on page 123 for more information.
Adapter Configuration
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>
482 OpenDeploy Administration Guide
Software Configuration Management Adapters
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">
Note the use of three slashes (“///”).
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:
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 (PvcsScm.dtd) for a list of syntax rules. This file resides in the following location:
od-home/adapters/payload/scm/pvcs/dtd/PvcsScm.dtd
484 OpenDeploy Administration Guide
Software Configuration Management Adapters
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"/>
See “Specifying the Payload Adapter” on page 123 for more information.
Adapter Configuration
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>
The following sample demonstrates shows this configuration:
<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
Refer to annotations in this schema file for descriptions of each item.
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
486 OpenDeploy Administration Guide
Software Configuration Management Adapters
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"/>
See “Specifying the Payload Adapter” on page 123 for more information.
Adapter Configuration
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
The following sample demonstrates shows this configuration:
<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
Refer to annotations in this schema file for descriptions of each item.
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
488 OpenDeploy Administration Guide
Software Configuration Management Adapters
deferred deferred[:add|:addfromarchive|:checkin|:drop|:import|:move|:rename|:updaterevision|:all]
memberOnBranch memberonbranch
unresolvedMerges unresolvedmerges
pending pending[:add|:addfromarchive|:drop|:import|:movememberfrom|:movememberto|:renamefrom|:renameto|:update|:updaterevision|:all]
workInProgress workinprogress
sparseContents sparsecontents
hostname --hostname=server
port --port=number
userName --user=name
password --password=password
recurse -R
sandbox --sandbox=sandbox
mergeType --mergeType=[confirm|cancel|automatic|manual]
onMergeConflict --onMergeConflict=[confirm|cancel|mark|launchtool|highlight|error]
byCP --[np]byCP
includeDropped --[no]includeDropped
merge --[no|confirm]merge
expand --[no|un]expand
overwriteChanged -f
overwriteIfPending --[no|confirm]overwriteIfPending
overwriteDeferred --[no|confirm]overwriteDeferred
overwriteUnchanged --[no]overwriteUnchanged
populate --[no]populate
restoreTimestamp --[no]restoreTimestamp
Attribute Option
489
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”>
</payLoadProperties>
See “Specifying the Payload Adapter” on page 123 for more information.
Adapter Configuration
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.
<!DOCTYPE websphere SYSTEM "file:///od-home/adapters/delivery/appserver/websphere/dtd/WebSphereAppServer.dtd">
<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>
490 OpenDeploy Administration Guide
IBM WebSphere Portal
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">
Note the use of three slashes (“///”).
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
492 OpenDeploy Administration Guide
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.
494 OpenDeploy Administration Guide
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.
496 OpenDeploy Administration Guide
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.
498 OpenDeploy Administration Guide
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
500 OpenDeploy Administration Guide
Index
AACDeploy element 461ACEsperm 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
502 OpenDeploy Administration Guide
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
504 OpenDeploy Administration Guide
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
506 OpenDeploy Administration Guide
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
508 OpenDeploy Administration Guide
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
compatibility 185file system-based 181, 368pattern-based 182, 369
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
510 OpenDeploy Administration Guide
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
compatibility 185file system-based 179, 367pattern-based 180, 368
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
512 OpenDeploy Administration Guide
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
514 OpenDeploy Administration Guide
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
516 OpenDeploy Administration Guide
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
518 OpenDeploy Administration Guide
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
520 OpenDeploy Administration Guide