Open Deploy Admin Strati On Guide

OpenDeploy® Administration Guide Release 6.1

© 1997-2006 Interwoven, Inc. All rights reserved. No part of this publication (hardcopy or electronic form) may be reproduced, translated into another language, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written consent of Interwoven. Information in this manual is furnished under license by Interwoven, Inc. and may only be used in accordance with the terms of the license agreement. If this software or documentation directs you to copy materials, you must first have permission from the copyright owner of the materials to avoid violating the law which could result in damages or other remedies. Interwoven, TeamSite, Content Networks, OpenDeploy, MetaTagger, DataDeploy, DeskSite, iManage, LiveSite, MediaBin, MetaCode, MetaFinder, MetaSource, OpenTransform, Primera, TeamPortal, TeamXML, TeamXpress, VisualAnnotate, WorkKnowledge, WorkDocs, WorkPortal, WorkRoute, WorkTeam, the respective taglines, logos and service marks are trademarks of Interwoven, Inc., which may be registered in certain jurisdictions. All other trademarks are owned by their respective owners. Some or all of the information contained herein may be protected by patent numbers: US # 6,505,212, EP / ATRA / BELG / DENM / FINL / FRAN / GBRI / GREC / IREL / ITAL / LUXE / NETH / PORT / SPAI / SWED / SWIT # 1053523, US # 6,480,944, US# 5,845,270, US #5,384,867, US #5,430,812, US #5,754,704, US #5,347,600, AUS #735365, GB #GB2333619, US #5,845,067, US #6,675,299, US #5,835,037, AUS #632333, BEL #480941, BRAZ #PI9007504-8, CAN #2,062,965, DENM / EPC / FRAN / GRBI / ITAL / LUXE / NETH / SPAI / SWED / SWIT #480941, GERM #69020564.3, JAPA #2968582, NORW #301860, US #5,065,447, US #6,609,184, US #6,141,017, US #5,990,950, US #5,821,999, US #5,805,217, US #5,838,832, US #5,867,221, US #5,923,376, US #6,434,273, US #5,867,603, US #4,941,193, US #5,822,721, US #5,845,270, US #5,923,785, US #5,982,938, US #5,790,131, US #5,721,543, US #5,982,441, US #5,857,036, GERM #69902752.7or other patents pending application for Interwoven, Inc. This Interwoven product utilizes third party components under the following copyright with all rights reserved: Copyright 1995-1999, The Apache Group (www.apache.org); Copyright 1986-1993, 1998, Thomas Williams, Colin Kelley. If you are interested in using these components for other purposes, contact the vendor.

Interwoven, Inc. 803 11th Ave. Sunnyvale, CA 94089 http://www.interwoven.com Printed in the United States of America Release 6.1 Part #90-21-00-610-300 April 2006

Table of Contents About This Book Notation Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Other OpenDeploy Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OpenDeploy Installation Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database Deployment for OpenDeploy Administration Guide . . . . . . . . . . . . . . . . . . OpenDeploy Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OpenDeploy Release Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Online Help. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 1: Getting Started Starting OpenDeploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Starting the User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Stopping OpenDeploy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running OpenDeploy as Non-Administrator or Non-Root. . . . . . . . . . . . . . . . . . . . . . . . . . . Running OpenDeploy on Windows as Non-Administrator . . . . . . . . . . . . . . . . . . . . . Running OpenDeploy on UNIX as Non-Root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Refreshing the OpenDeploy Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OpenDeploy User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Browser Refresh Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing the User Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logging In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Timeout Setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OpenDeploy Server Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding OpenDeploy Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing Server Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting OpenDeploy Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Monitoring Server Logs and Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Server Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing Server Group Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reconnecting to a Restarted OpenDeploy Server . . . . . . . . . . . . . . . . . . . . . . . . . . . Determining the OpenDeploy Server Version. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Displaying the OpenDeploy Server Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Composing Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using a Text or XML Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Deployment Configuration Composer . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Deployment Configuration Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Uploading Deployment Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Organizing Deployment Configurations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Deployment Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Deployment Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Directory Permissions for Deployment Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . Assigning Access Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

13 14 15 15 15 15 15 15

17 17 17 19 20 21 21 23 24 24 24 28 29 29 30 30 32 33 33 34 35 35 40 43 47 47 48 49 49 49 50 52 53 54 55 55 56 3

Running Deployments from the User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Starting a Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performing a Test Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performing a Simulated Deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Cancelling Deployments in Progress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Monitoring Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deployments Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Details Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Source Deployments Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Target Deployments Window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deployment Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running Deployments from the Command Line. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Authorization Checking. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Starting a Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performing a Simulated Deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying a Deployment Instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running Deployments Asynchronously . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Cancelling a Deployment in Progress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Roles and Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Administrator Role. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User Role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Server Access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deployment and Deployment Groups Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Authorizing Deployments and Deployment Groups from the Command-Line. . . . . . . . Role Access in TeamSite Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 2: Deployment Types

56 56 59 59 60 63 64 64 65 66 66 67 67 68 68 69 69 70 70 71 71 72 73 74 76 78

79

Deployment Configuration Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Understanding the Configuration DTDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Encoding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Naming Deployment Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Deployment Configuration Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Specifying the Deployment Host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Specifying the Connection Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Configuring Concurrency Management Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Target Replication Farms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Specifying the Replication Farm Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Configuring the Replication Farm within the Deployment Configuration . . . . . . . . . . . 90 Referencing Target Replication Farms in the Nodes Configuration File . . . . . . . . . . . . 92 Reverse Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Source File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Target File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 File Filters and Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Windows Path Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Deployment Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

4

OpenDeploy Administration Guide

Transactional . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Definition-Specific Configurations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Directory Comparison Deployments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Defining the Source File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Defining the Target File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 Resolving Time Zone Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Deploying Files When Extended Attributes Change. . . . . . . . . . . . . . . . . . . . . . . . . 106 TeamSite Comparison Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Defining the Source TeamSite Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 Defining the Target File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 Deploying TeamSite Extended Attributes with TeamSite Files . . . . . . . . . . . . . . . . . . 113 Comparing Files with Extended Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Writing Extended Attributes to a Manifest File. . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 Use With Deploy and Run Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 File List Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 Defining the Source File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 Editing the File List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 Specifying the File List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 Defining the Target File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Using doDeletes with File List Deployments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 Configuring TeamSite Source File Locations on UNIX Hosts . . . . . . . . . . . . . . . . . . . . . . . . 120 Recommended Path Prefixes for Directory Comparison, File List or Payload Deployments 120 Recommended Path Prefix for TeamSite Comparison Deployments. . . . . . . . . . . . . . 121 Payload Adapter-Based Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Defining the Source File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 Specifying the Target File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Specifying the Payload Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Providing Input to the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 OpenDeploy Query Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Deployment Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 Writing Payload Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 Metadata-Based Deployments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 Data Asset Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 Database Auto-Synchronization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 Standalone Database Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 Target-Side Database Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Synchronized Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Defining Source-Based Overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 Defining Target-Based Overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 Specifying Different Target Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 Defining Features on a Target-Specific Basis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 Deployment Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 Using Example and Sample Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 Example Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 Sample Configurations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 Redeploying Legacy Web Sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

5

Chapter 3: Content Delivery Methods

145

Transactional Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Fan-Out Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EasyDeploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transactional Targets in Fan-Out Deployments. . . . . . . . . . . . . . . . . . . . . . . . . . . . Determining the Success Criteria (Quorum) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Multi-Tiered Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EasyDeploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transactional Targets in Multi-Tiered Deployments . . . . . . . . . . . . . . . . . . . . . . . . Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Routed Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How Route Definitions Are Determined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying End Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Resolving Unspecified Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . File Manifest Determination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transactional . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Manifest Information Stream Format Requirement . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Route Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Route Segments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Next-Tier File Locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Referencing the Route Definition in the Deployment Configuration . . . . . . . . . . . . . Specifying a Common Host for Simplified Checking . . . . . . . . . . . . . . . . . . . . . . . . Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reverse Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deployment Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Certified Limits for Number of Deployment Legs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Certification Factors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Environmental Factors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Examples and Recommendations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 4: Deployment Features

175

Filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filter Placement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Inclusion Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Exclusion Filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Exception Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Combining Filter Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Path Syntax for Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Supported Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Comparison Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Date-Based Comparison Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transfer Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Permission Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Cross-Platform Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User and Group Ownership Transferal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting the File Transport Buffer Size (Bandwidth Throttling) . . . . . . . . . . . . . . . . . . . . . . . Using OpenDeploy with ACLs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6

145 146 147 147 148 149 152 152 153 156 157 159 159 161 161 162 162 163 164 166 167 167 168 169 170 171 171 172 172 175 177 179 181 182 185 185 186 187 189 190 192 193 195 195 196 198

OpenDeploy Administration Guide

ACL Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ACE Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ignoring and Preserving ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling UNIX-Based Deployments When Extended ACLs Are Present. . . . . . . . . . . Deploying Symbolic Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameter Substitution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Default Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running Deployments with Parameter Substitution. . . . . . . . . . . . . . . . . . . . . . . . . Use with Deployment Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Use with Scheduled Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Use with Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameter Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Utilizing the Delivery Adapter Framework. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How Delivery Adapters are Incorporated into Deployments . . . . . . . . . . . . . . . . . . . Configuring Delivery Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Writing Delivery Adapters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JDK Requirement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample Delivery Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DataDeploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling DataDeploy on the Source Base Server . . . . . . . . . . . . . . . . . . . . . . . . . . . Database Deployment in the Deployment Configuration . . . . . . . . . . . . . . . . . . . . .

Chapter 5: Deploy and Run

215

Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Interacting with the Windows Desktop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deployment-Level Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Task-Level Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Allowed Deploy and Run Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ordering of Deploy and Run Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Usage of the Deployment Information Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Information Stream Output Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disabling Deploy and Run Executions on the Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deploying to a Package File Using Deploy and Run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Secure Invocation of External Applications on UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 6: Scheduled Deployments

198 198 199 200 201 203 204 204 206 206 206 207 208 209 210 211 211 212 213 213 214 214 214 215 216 216 217 218 227 229 230 231 231 233 233 234

235

Scheduling from the User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Resolving Time Zone Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Scheduling Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Schedules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Scheduled Deployment Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing Scheduled Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting Scheduled Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Activating and Deactivating Scheduled Deployments . . . . . . . . . . . . . . . . . . . . . . . . Scheduling from the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

236 236 237 239 239 240 241 241 242

7

Adding a Schedule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Scheduled Deployment Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting a Schedule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Activating and Deactivating a Schedule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reactivating Schedules During or Past Their Effective Period. . . . . . . . . . . . . . . . . . . . . . . .

Chapter 7: Logging

251

Log File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Log File Permissions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Log Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Log Files from a Text Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Log Files from the OpenDeploy User Interface . . . . . . . . . . . . . . . . . . . . . Base Server Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Receiver Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Macro Deployment Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Source Macro Deployment Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Receiver Macro Deployment Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Micro Deployment Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Source Micro Deployment Log. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Receiver Micro Deployment Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logging Levels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining Logging Levels in the User Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining Logging Levels from the Command Line. . . . . . . . . . . . . . . . . . . . . . . . . . Logging Configuration Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Base Server and Receiver Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deployment Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logging Rules Hierarchy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Base Server and Receiver Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Macro and Micro Deployment Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Log File Size Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Rollover Threshold Size Determination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Rolled Over Log File Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Log File Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Base Server and Receiver Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deployment Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Administration Server Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reporting Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adapter Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 8: Reporting

251 251 252 252 252 254 255 256 256 257 258 259 261 262 262 262 263 263 264 264 264 265 265 266 266 267 267 267 268 268 269

271

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

8

242 245 247 248 250

272 272 273 275 276 276 277 277 278

OpenDeploy Administration Guide

Reporting Server Database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Upgrading Reporting Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Upgrading the Default Reporting Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding Servers to the Reporting Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using a Third-Party Database for Store-and Forward System . . . . . . . . . . . . . . . . . . Custom Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Custom Report Queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Generating Custom Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Downloading Custom Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Saving Custom Reports as a Quick Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DAS Custom Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ControlHub Custom Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SQL Query Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SQL Report Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Generating SQL Query Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Downloading an SQL Query Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Saving an SQL Query Report as a Quick Report . . . . . . . . . . . . . . . . . . . . . . . . . . . Quick Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding New Entries to Quick Report List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing Existing Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing Report Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reporting Database Sizing Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sending OpenDeploy Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Receiving OpenDeploy Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database Auto-Synchronization (DAS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 9: Encryption

317

Symmetric Key Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring OpenDeploy for Symmetric Encryption . . . . . . . . . . . . . . . . . . . . . . . . Using Symmetric Encryption with Reverse Deployments . . . . . . . . . . . . . . . . . . . . . Secure Data Transfer with SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Obtaining Additional SSL Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up for SSL Private Keys and Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up the Certificate Authority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Generating a Certificate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Support for Third-Party Certificate Authority . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing OpenSSL Defaults. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SSL Configuration and Deployment Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Verifying Certificates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Multiple Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring OpenDeploy for SSL Data Transfer Encryption . . . . . . . . . . . . . . . . . . . Ciphers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing the SSL Encryption Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Support for Third-Party Certificate Authority When Using SSL Encryption . . . . . . . .

Chapter 10: Composing Deployments

280 291 292 294 295 297 298 300 304 305 305 307 310 311 312 312 313 313 314 314 314 315 316 316 316 316 317 317 318 319 319 319 321 323 325 326 326 327 328 329 330 332 333 333

335

Deployment Configuration Composer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

9

Tree and Errors Tabs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Details Pane. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Types of Deployment Configuration Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Global Deployment Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Definition Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a New Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Naming the Deployment Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying the Parameter Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying the Log Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Verifying or Changing the Source Host Name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring the Concurrency Management Settings . . . . . . . . . . . . . . . . . . . . . . . . Specifying the Connection Timeout Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Deployment Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying the File Transport Buffer Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Naming the Replication Farm Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding Target Host Nodes to the Replication Farm Element . . . . . . . . . . . . . . . . . . Assigning Next-Tier Deployments to Target Hosts . . . . . . . . . . . . . . . . . . . . . . . . . Specifying a Transactional Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Deploy and Run. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying a Routed Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Naming and Adding Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Selecting the Definition Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining the Source File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining a Subdirectory Within the Source File Location . . . . . . . . . . . . . . . . . . . . . Configuring Payload Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Applying Source-Side Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Following Source-Side Symbolic Links in Deployments . . . . . . . . . . . . . . . . . . . . . . Designating Alternate Targets from the Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining the Target File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying the Target Replication Farm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Applying Comparison Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Applying Transfer Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Applying Permission Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring for Use with Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Applying Target-Side Filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Saving the Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing Deployment Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing Configuration From Previous OpenDeploy Releases. . . . . . . . . . . . . . . . . . . Creating DataDeploy Wrapper Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing Remote Upgrade Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Remote Action Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Target Progress Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Initial Polling Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 11: Syndication

389

How Syndication Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Offers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Schedules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

10

337 338 339 339 340 341 342 342 342 343 344 344 344 346 347 347 348 349 349 356 357 357 358 361 362 366 371 372 373 375 375 376 378 381 381 382 383 383 384 385 386 387 388 390 390 390 391

OpenDeploy Administration Guide

User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Offers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Payload Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Schedules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Suspending Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Subscriptions from the Offer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Command-Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Offers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying the Deployment Schedule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Processing the Subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Displaying Offers and Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting Offers and Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Suspending Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Activating Suspended Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Schedule Modifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 12: Web Services

427

Using Web Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OpenDeploy Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Access Server Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tools and Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 13: Archival Module

428 429 429 429

431

Archiving with Standalone OpenDeploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Archiving with ControlHub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Archival with ControlHub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running Archival Module Tasks from the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . .

Appendix A: Delivery Adapters

391 391 395 400 406 407 407 408 408 410 416 420 422 423 423 424 425 426

431 432 432 432 437

439

Generic Delivery Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adapter Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deployment Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adapter Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deployment Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Email Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adapter Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deployment Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Network Appliance NetCache Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adapter Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deployment Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Retrying When Push Fails But Overall Deployment Succeeds . . . . . . . . . . . . . . . . . . Internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BEA WebLogic 8 Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adapter Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deployment Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

439 440 440 441 441 442 442 443 443 444 445 446 446 447 448 448 450 11

Use of “Upload” Directory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BEA WebLogic 9 Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adapter Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deployment Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IBM WebSphere Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adapter Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deployment Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BEA Bulk Loader Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adapter Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deployment Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Microsoft Application Center Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adapter Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deployment Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Microsoft COM+ Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adapter Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deployment Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Microsoft Global Assembly Cache (GAC) Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adapter Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deployment Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SunCIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Appendix B: Payload Adapters

450 451 451 451 453 453 457 458 458 460 460 460 463 464 464 467 468 468 469 470

471

JDK Requirement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . File List Differential Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing the File List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Software Configuration Management Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IBM Rational ClearCase Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Microsoft Visual SourceSafe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Serena (Merant) PVCS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Concurrent Versions System (CVS). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MKS Source Integrity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IBM WebSphere Portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

471 471 472 472 473 474 475 475 478 482 485 487 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

Monospace

Monospaced italic

Book titles appear in italics. Terms are italicized the first time they are introduced. Important information may be italicized for emphasis. Commands, command-line output, and file names are in monospace type. For example: The iwodstart command-line tool starts an OpenDeploy deployment task. Monospaced italics are used for command-line variables.For example: iwodstart deployment

Monospaced bold

This means that you must replace deployment with your values. 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

[] |

14

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.

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: Service

Software

Interwoven OpenDeploy 60 Service OpenDeploy base server or receiver Interwoven OpenDeploy UI Admin Administration server Interwoven OpenDeploy 60 SNMP Service SNMP server 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: 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 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. 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 command 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: Service

Software

Interwoven OpenDeploy 60 SNMP Interwoven OpenDeploy UI Admin Interwoven OpenDeploy 60 Service

SNMP server Administration server OpenDeploy base server or receiver

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 popup menu to stop the base server or receiver software.

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: 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 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

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 appropriate boxes. 5. Click OK and close the Services window. 6. Restart the OpenDeploy service you had previously stopped. See “Starting OpenDeploy” 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 nonroot 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 owner group od-home

Displays help information. User name or ID Group name or ID 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 time su - 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_" and group="_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 commandline 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 -h -v -q

-listpathreg

Uses OpenDeploy instance instName. Displays usage information. Displays version information. Disables messages generated when there are active deployments in progress at the time iwodcmd serverreset is run. 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" ...>

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 timeout 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:

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 — „ saturn — „ venus — 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 reaccess 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 -h -v -q

48

Uses OpenDeploy instance instName. Displays help information. Displays version information. Omits displaying the number of active deployments.

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 configuration 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 odhome/(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 configuration 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 deployment 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/internal od-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 performing 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 “Performing 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. „ „ „ „ „ „

64

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.

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 -v deployment -async

-inst instName

Displays usage information. Displays version information. Name of the deployment to start. 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. Uses OpenDeploy instance instName.

67

Getting Started

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. Enables the simulated deployment feature. See “Performing a Simulated Deployment” on page 59 for more information. Logging level with verbose or normal as args. See “Defining Logging Levels from the Command Line” on page 262 for more information.

-k "key=value"

-sim

-V arg

The iwodcmd deployment: „

start

command returns the following codes regarding the status of the

— succeeded „ 1 — failed to start „ 2 — ran and returned a failed status „ 9 — completed with errors 0

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 using the following syntax:

start command with the -inst instance

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 -v deployment

70

Displays usage information. Displays version information. Name of the deployment to cancel.

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 oduser 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 Authorized 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 interface

„

iwodcmd 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: jdoe rroe jsmith

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: deployment1 deployment2 depgroup1/

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 -v -u user-filelist -d deployment-filelist

-a add

-a remove

-a set

-odinst instName

Displays usage information. Displays version information. Specifies the path to the user file list. Each user entry must be on a separate line. Specifies the path to the deployment file list. Each deployment group or individual configuration name must be on a separate line. Adds deployment authorizations to users in the list. These are added to any existing authorizations already present. 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. 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 deploymentfilelist value. 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 doublequote 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:

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:

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:

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:

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

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: „

(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

<element_name>

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:

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:

For French and German, the encoding value would be:

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: <deploymentConfiguration> <nodeRef useNode="MyLocalHost"/> <definition name="web_files"> <source> <pathSpecification> <path name="."/> <deployment transactional="no"> <execDeploymentTask useDefinition="web_files"/>

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. <deploymentConfiguration> <nodeRef useNode="a"/> <nodeRef useNode="b"> <nodeRef useNode="c"/> <definition name="web_files"> <source> <pathSpecification> <path name="this"/> <excludePath subPath="out/exes"/> <excludePattern regex="\.obj$"/>

85

Deployment Types

<deployment transactional="no"> <execDeploymentTask useDefinition="web_files"> <deployNRun> <script cmd="C:\bin\email_admin.bat -user [email protected]" where="C:\temp" async="no"/> <script cmd="C:\bin\email_admin.bat -user [email protected]" where="C:\temp" async="no"/> <script cmd="C:\bin\email_admin.bat -user [email protected]" where="C:\temp" async="yes"/>

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> ...

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> ...

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> ...

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: ... ...

Within the replicationFarmLink element are the following child elements: „

— 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. internal

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:

while in the following example, the target replication farm MyTargetReplicationFarm2 resides in the sending server’s nodes configuration file: <external name="MyTargetReplicationFarm2"/>

89

Deployment Types

See “Referencing Target Replication Farms in the Nodes Configuration File” on page 92 for more information on that feature. Use of useReplicationFarm Element for Backwards Compatibility

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

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> ... ... ...

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: <nodeRef useNode="england"/> <nodeRef useNode="france"/> <nodeRef useNode="spain"/>

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"/>

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: <nodeRef useNode="mars"> <nodeRef useNode="mars">

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"/> ...

91

Deployment Types

You could then use these unique logical names for each useNode attribute value in your deployment configuration: <nodeRef useNode="mars1"> <nodeRef useNode="mars2">

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: <external name="MyTargetReplicationFarm2"/>

Specify the unique name of the replicationFarm element residing in the nodes configuration file as the value for the external element’s name attribute value. See “Specifying the Replication Farm Location” on page 89 for more information. Refer to “Defining Target Nodes” on page 89 in the OpenDeploy Installation Guide for more information on defining target replication farms in the nodes configuration file. Reverse Deployments Target replication farms can be specified in reverse deployments. The replicationFarmLink element and its child elements are defined in the reverseSource element, and are configured in the same manner. See “Reverse Deployments” on page 168 for more information on the reverse deployment feature.

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> ... ... ...

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: „

— 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. remoteDiff

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> ... ...

or <definition name="webfiles"> <source> <areaDiff area="/default/main/dev/EDITION" previousArea="/default/main/dev/EDITION/IW_PREV"> ... ...

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: <pathSpecification> <path name="daily">

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: <pathSpecification> <path name="daily"> <pathSpecification> <path name="monthly">

95

Deployment Types

By combining the subdirectories specified by the pathSpecification element with the area attribute value, the final source file locations for this deployment are: /dev/website/files/daily

and

/dev/website/files/monthly

If you do not want to specify a subdirectory with the area attribute value, you must still include the pathSpecification element in the configuration. You must give the path element’s name attribute the value “.”. For example: <pathSpecification> <path name=".">

You can configure other features within the pathSpecification element, such as such as filters and rules. These features are described in Chapter 4, “Deployment Features” on page page 175. Defining Multiple Source File Locations

You can have multiple source file locations configured within the definition. For example: <definition name="webfiles"> <source> ... ... ...

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"> ...

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 likenamed 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:

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: Path Type

Windows 2000

Windows 2003

Local drive letter Remote mapped drive letter UNC path location

yes yes yes

yes no yes

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.

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"> ...

Definition-Specific Configurations Within the deployment element you can configure certain functionality on a definitionspecific 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"/>

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 useDefinition="asia"> ...

Deploy and Run

Within the execDeploymentTask element, you can configure Deploy and Run scripts. Deploy and Run allows you to configure OpenDeploy to execute an external script at a specified stage of the deployment. This stage can be the deployment of a particular type or class of file or directory, or even the success of the deployment itself. See “Utilizing the Delivery Adapter Framework” on page 208 for more information. Deploy and Run scripting is assigned on a definition-specific basis within the execDeploymentTask element. The deployNRun child element is the container for Deploy and Run configuration. For example: <execDeploymentTask useDefinition="europe"> <deployNRun> ...

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

source file system location.

target file system location.

Source and target file directories are compared.

/dev/website/files

/website/files

Comparison differences are deployed to target node.

mars

venus

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> ...

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>

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: ...

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: <pathSpecification> <path name="monthly"/>

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: <pathSpecification> <path name="monthly"/> <pathSpecification> <path name="weekly"/>

You should not configure multiple pathSpecification elements in the same definition that specify the same target file location path. The pathSpecification and path elements are required in the deployment configuration file. However, if you do not want to specify a source file location any narrower than the specified area, you can simply list the path element’s name attribute as ".", which indicates the area location. The following example shows a simple source element where no source file location is specified beyond the area: <pathSpecification> <path name="."/>

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:

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> ...

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. TeamSite area and previous area are compared. Target node file system location.

/default/main/dev/ EDITION/Jan_04

/default/main/dev/ EDITION/IW_PREV/Dec_03

/website/files

Comparison differences are deployed to venus.

mars

venus

Figure 2: TeamSite Comparison Deployment

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> <areaDiff area="/default/main/dev/EDITION/Jan_04" previousArea="/default/main/dev/EDITION/Dec_03"> ...

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 UNIXstyle 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: <areaDiff area="/default/main/dev/EDITION" previousArea="/default/main/EDITION/INITIAL"> <pathSpecification> <path name="."/>

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: <areaDiff area="/default/main/dev/EDITION" previousArea="/default/main/dev/EDITION/IW_PREV"> <pathSpecification> <path name="monthly"/>

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: <areaDiff> area="/default/main/dev/EDITION" previousArea="/default/main/EDITION/INITIAL"> <pathSpecification> <path name="."/>

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:

or



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:

or



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:

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:

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: „ „ „ „ „

114

Deployment name — gen_EAs Definition name — def1 Source host — mars Target host — venus pathSpecification element order number — 0

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-tuple-data version="2.0.0"> x /data/OpenDeployNG/tmp/ testcontent/alpha Original y y /data/OpenDeployNG/tmp/ testcontent/alpha Original z z /data/OpenDeployNG/tmp/ testcontent/alpha Original a

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:
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:
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

File list is referenced and applicable files are selected for deployment from file system location. Target node file system location.

/OpenDeploy/ filelists/filelist1.txt

/dev/website/files

/website/files

Files present in the list are deployed to the target node.

mars

venus

Figure 3: File List Deployment

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> ...

or <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.html www/andre/index.html www/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.html dev/website/files/www/andre/index.html dev/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: ...

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.html dev/website/files/www/andre/index.html symlink1/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:

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:

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.

Payload adapter applies selection criteria to files in source file location. Selected files are listed in file manifest. payload adapter File system location or TeamSite area.

Target file system location.

Files in manifest are compared with target and deployed or are deleted on target.

mars

venus

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> <payload area="/dev/website/files"> ...

122

OpenDeploy Administration Guide

Payload Adapter-Based Deployments

or <source> <payload area="/default/main/dev/EDITION/Jan_04"> ...

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 .../> ...

or the source server’s base server configuration file (by default, odbase.xml): <deployServerConfiguration> ... <payLoadProperties ... /> ...

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> ...

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> ...

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> ... ...

Within the query element is the predicate element: <predicate operator="GT" value="100"> ...

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

‰

— 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: CONTAIN

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: „

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: textType

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” (). The key is identified as being text-based (textType): <predicate operator="EQ" value="MBA">

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">

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: „

— 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. and

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”: <predicate operator="GT" value="01/01/2000"> <predicate operator="EQ" value="economics">

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> ...

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. Payload adapter queries metadata in database. Selected files are listed in file manifest. payload adapter File system location or TeamSite area.

OpenDeploy process Target file system location.

Database containing indexed file metadata. mars

Files in manifest are compared with target and deployed or are deleted on target.

venus

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.

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: „

— 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. TQueryGenericRetrieval

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: <payLoadProperties name="com.interwoven.od.adapter.retrieval.database. TGenericDatabaseRetrieval" parameter="driver=DRIVERNAME, url=URL, user=USER, password=PASSWORD/>

or <payLoadProperties name="com.interwoven.od.adapter.retrieval.database. IWQueryDatabaseRetrieval" parameter="driver=DRIVERNAME, url=URL, user=USER, password=PASSWORD, table=TABLENAME"/>

If you are using the IWQueryDatabaseRetrieval adapter, you must specify the table name (table=TABLENAME) as a value of the parameter attribute. See “Specifying the Payload Adapter” on page 123 for more information on configuring the payload adapter.

131

Deployment Types

For both adapters, the PATH column has to already exist in the database. These adapters assume that the database schema consists of a single table with a column for the file path names and a column for each key value (metadata name) used in the query. The PATH column can contain a path relative to the specified TeamSite area if you are deploying TeamSite assets, but should contain the full file system path if you are deploying other types of assets. All path types must be consistent. You cannot use full paths for some column entries and relative paths for other column entries. Next, you must configure the deployment as a payload adapter-based deployment. Because the source file location is a TeamSite area, the iwStore element should be specified in the configuration: <source> <payload area="..."> <payLoadRules> ...

If you are using the TQueryGenericRetrieval adapter, you must include the query as a CDATA string under the payLoadRules element, for example: <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> ... <predicate operator="EQ" value="MBA">

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> <payload area="..."> <payLoadRules> ...

Metadata-Based Deployments Using Other Adapters

You have the option of using your own adapter for metadata-based deployments rather than using the Intelligent Delivery module's adapters. In some cases, such as if the metadata is stored in a proprietary repository, only a user-provided adapter will work in the deployment. The payload adapters you implement for metadata-based deployments must accept the query as a PCDATA string, or support the OpenDeploy query syntax. Writing an adapter that supports the OpenDeploy query syntax requires that the user-defined adapter process the query XML string to convert to the syntax of customer-specific search and index engine. You can specify the source file location as either a TeamSite area or arbitrary repository. It is the responsibility of the adapter to determine the file paths to deploy and to return those as a manifest.

133

Deployment Types

When you are writing a payload adapter for use in a metadata-based deployment, you must consider the following items: „

What type of query is being employed in the deployment configuration (PCDATA or OpenDeploy query syntax)? „ How will the input query from the deployment configuration be converted to a query on the metadata repository? „ What is the type of source file location (TeamSite area or another location) from which the files matching the query criteria will be deployed? See “Writing Payload Adapters” on page 129 for general information on how to write a payload adapter. You are not required to have the Intelligent Delivery module installed and licensed if you are providing your own adapter in a metadata-based deployment. You must specify your user-provided adapter in the payLoadProperties element in the base server configuration file. See “Specifying the Payload Adapter” on page 123 for more information. Logging Payload adapters have their own log files. See “Adapter Logging” on page 269 for more information.

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.

TeamSite

OpenDeploy

DCR or EAs are modified

OpenDeploy uses DAS synchronize TeamSite data with database.

TeamSite event server triggers OpenDeploy.

database

TeamSite data is synchronized on the database.

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. 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.

structured content files Structured content files are deployed to relational database using JDBC

source

database

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.

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.

Structured content is deployed to database. using JDBC.

Structured content files are deployed to target

source

target

database

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.

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.

Code and content files are deployed to target.

XML content is deployed to database. using JDBC.

Structured content files are deployed to target source

target

database

Figure 9: Synchronized Database Deployment

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.

Code and content files are deployed to target. target XML content is deployed to database. using JDBC.

Code and content files are deployed to target. Structure content files are deployed to target target

source

database

Code and content files are deployed to target. target

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.

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> ... <pathSpecification> ...

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. <nodeRef useNode="mars"/> <nodeRef useNode="jupiter"> <nodeRef useNode="saturn">

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 sourcebased 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. OpenDeploy references a transactional deployment configuration.

Deployment of files to venus is unsuccessful, and is detected by OpenDeploy.

mars

OpenDeploy restores venus’ file area to its original state with no content change noticeable.

venus

Figure 1: Transactional Deployment

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. OpenDeploy references a fan-out deployment configuration.

venus Files are deployed to targets.

mars

jupiter

mercury

Figure 2: Fan-Out Deployment

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: <nodeRef useNode="venus"/> <nodeRef useNode="jupiter"/>

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"/>

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 fanout 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. Deployment of files to jupiter is successful.

Overall fan-out deployment is unsuccessful, jupiter is restored.

OpenDeploy references a fan-out deployment configuration.

jupiter Deployment of files to venus is unsuccessful, and is detected by OpenDeploy.

mars

OpenDeploy restores venus’ file area to its original state with no content change noticeable.

venus

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 element. For example:

replicationFarm

<nodeRef useNode="venus"/> <nodeRef useNode="jupiter"/> <nodeRef useNode="mercury"/>

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.

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. OpenDeploy references a fan-out deployment configuration. quorum=2 transactional=yes

venus Files are deployed to targets.

mars

jupiter

mercury

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 nexttier 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.

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. OpenDeploy on jupiter references its own deployment configuration and redeploys received files to next tier of targets.

OpenDeploy on mars references a fanout deployment configuration and deploys to first tier of targets.

venus saturn Files are deployed to targets. Files deployed to the targets. mars

jupiter

pluto mercury

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.

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: <nodeRef useNode="venus"> <nodeRef useNode="jupiter"/> <nodeRef useNode="mercury"/>

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: „

— 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

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: <nodeRef useNode="venus"> ...

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 currenttier 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.

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. Multi-tiered deployment runs where every sending server at each tier has multiTierTransactional="yes" configured.

venus saturn

mars

jupiter

pluto mercury

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.

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> ... <nodeRef useNode="mars"> <definition name="def1"> <source> <pathSpecification> <path name="."/> <definition name="def2"> <source> <pathSpecification> <path name="."/> ...

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 sourcebased overrides: <deploymentConfiguration> ... <nodeRef useNode="mars"> <definition name="def1"> <source> ... <pathSpecification> <path name="."/> ...

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:

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:

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. Allowed route segments: mars —> venus venus —> jupiter mars —> mercury mercury —> jupiter jupiter —> saturn

jupiter —> pluto

venus saturn

mars

jupiter

pluto mercury

Figure 7: Routed Deployment

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: „ „ „ „ „ „

158

mars —> mercury mercury —> jupiter mars —> venus venus —> jupiter jupiter —> saturn jupiter —> pluto

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: <nodeRef useNode="venus"/> <nodeRef useNode="mercury"/> <nodeRef useNode="saturn"/> <nodeRef useNode="pluto"/>

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.

Allowed route segments: mars —> england england —>london.* england —>scotland.* england —>wales.*

Allowed route segments: england —> londonExt england —> londonInt england —> scotlandA england —> walesZ

londonExt

londonInt

mars

england

scotlandA walesZ

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.

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 nexttier 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 ../> ... ...

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 ../> ... ... ...

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: „

— specifies the logical name of the node that is the source of the route segment, for example: fromNode

fromNode="mars"

This logical name must match the localNode element’s name attribute in the sending server’s configuration file, for example:

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 .../> ... <nodeInfo fromNode="mars" toNode="venus"/> <nodeInfo fromNode="mars" toNode="jupiter"/> <nodeInfo fromNode="mars" toNode="mercury"/> <nodeInfo fromNode="jupiter" toNode="saturn"/> <nodeInfo fromNode="jupiter" toNode="pluto"/>

You can specify a regular expression as the value for the toNode attribute. For example: <nodeInfo fromNode="england" toNode="london.*"/>

163

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"/> ...

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: „

— 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. {ORIGNODE}

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> ... ...

The routedDeployment element contains the following attributes: „

— 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: useRouteDefinition



„

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:

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. OpenDeploy references a reverse deployment configuration.

Base server initiates reverse deployment to reverse source. Files are reverse deployed back to the reverse target. mars (reverse target)

venus (reverse source)

Figure 9: Reverse Deployment

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. Allowed hosts: mars, venus Allowed directory for received files

Allowed host: mars

Base server initiates reverse deployment to reverse source. Files are reverse deployed back to the reverse target. mars (reverse target)

venus (reverse source)

Figure 10: Server Configuration for Reverse Deployments

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"> <sourceFilesystem area="C:\dev\website\files"> <pathSpecification> <path name="monthly"/> <pathSpecification>

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> <pathSpecification> <path name="aaa"/> <pathSpecification> <path name="bbb"/>

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> <pathSpecification> <path name="aaa"/> <definition name="def2"> <source> <pathSpecification> <path name="bbb"/>

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 sourceside, 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 targetside, 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> <pathSpecification> <path name="."/> ... ...

Target-Side Filters

Target-side filters can reside in the following locations: „

The targetRules child element of the source element: <source> <pathSpecification> <path name="."/> ... ...

„

The target element: ...

177

Deployment Features

„

A targetRules element at the node level: <nodeRef useNode="venus"> ...

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 sourceside 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:

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:

You can add inclusion paths to your deployment configuration file by adding another includePath element for each included path. For example:

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:

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:

You can specify multiple inclusion patterns for a deployment configuration file by adding another includePattern element for each pattern. For example:

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: <excludePath subPath="path_to_be_excluded"/>

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: <excludePath subPath="WebFiles/working"/> <excludePath subPath="WebFiles/intranet"/>

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: <excludePattern regex="pattern_to_be_excluded"/>

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: <excludePattern regex=".*\.html$"/> <excludePattern regex=".*\.txt$"/>

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: <excludePath subPath="path_to_be_excluded"/> <excludePattern regex="pattern_to_be_excluded"/> <exceptPath subPath="path_to_be_excepted"/>

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: <excludePattern regex=".*\.html$"/> <exceptPath subPath="reports/monthly/index.html"/>

Those files within the directory reports/monthly: reports/monthly/reports.html reports/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: <excludePath subPath="path_to_be_excluded"/> <excludePattern regex="pattern_to_be_excluded"/> <exceptPattern regex="pattern_to_be_excepted"/>

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: <excludePath subPath="reports/monthly"/> <exceptPattern regex="regex=".*\.html$"/>

Those files within the directory reports/monthly: reports/monthly/reports.doc reports/monthly/reports.pdf reports/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. Matches either x or y. Matches exactly n instances of preceding character (where n is an integer). Matches at least n instances of preceding character (where n is an integer). Matches at least n and at most m instances of preceding character (where n and m are integers). Matches any one of enclosed characters (specify range using hyphen, such as [0-9]. Matches any character not enclosed (specify range using hyphen, such as [^0-9]. Matches a line feed. Matches a tab.

^ $ * + ? . x|y {n} {n,} {n,m} [xyz] [^xyz] \n \t

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:

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"

and

ignoreUser="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 transferrelated 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:

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:

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 permissionrelated 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"

„

(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

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

„

(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

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:

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: „

— 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

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: <userTranslation from="jdoe" to="rroe"/>

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> ... ...

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: Sender Buffer Size (Bytes)

Target Buffer Size (Bytes)

Average Transfer Rate (Kilobytes Per Second)

8000 45555 262144 45555

8000 45555 262144 262144

48 88 36 69

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.

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.

ignoreAcls="no"

ignoreAcls="yes"

preserveAcls="no"

preserveAcls="yes"

Deployment includes ACLs for comparison but does not deploy the ACLs. Deployment does not include ACLs for comparison and does not deploy ACLs.

Deployment includes ACLs for comparison and does deploy the ACLs. Deployment does not include ACLs for comparison but does deploy the ACLs.

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.

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:

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:

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. FollowLinks Enabled?

Matching Target Result Contents

no no

none link, file, or directory none

yes

yes

202

link, file, or directory

The symbolic link is deployed to the target. The existing item is replaced by the symbolic link with the same name. 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. 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.

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 line tool. The syntax for using iwodcmd start with parameters is:

start

command-

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.

delivery adapter target

target file location

source file location

delivery adapter mars

venus

jupiter

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.

source file location

target file location

delivery adapter target

delivery adapter mars

jupiter

Figure 4: Delivery Adapter Using Loopback Deployment

209

Deployment Features

Configuring Delivery Adapters Delivery adapters are configured in the deployment configuration using the odAdapterSet element, which resides within the target element. ... ...

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 For example:

parameter attribute a null value. parameter=""

„

— 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

async

OpenDeploy Administration Guide

Utilizing the Delivery Adapter Framework

‰ ‰

— 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. ERROR

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:

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:

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 specific 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:

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 autosynchronization (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. after compare/before transfer after connection/before compare

after transfer/before disconnection

before connection

after disconnection

before deployment

beginning of deployment

after deployment after rollback

task-level basis (microdeploy)

end of deployment

deployment-level basis (macrodeploy)

Figure 1: Deploy and Run Stages in the Deployment

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 ...> <script .../> ...

The dnrDeploymentJob has the following associated attributes: „

— 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. location

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: \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 nontransactional deployments. Configuration

Transactional

Response Code Behavior



yes no



yes no

Deployment runs regardless, and returns status Completed and code 0. Deployment runs regardless, and returns status Completed and code 0.

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.

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> ... ...

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> ...

Within the deployNRun element is the configuration for the various supported task-level triggers and scripts: <deployment ...> <script .../> ... <execDeploymentTask useDefinition="webfiles"> <deployNRun> <script .../> <script .../> <script .../>

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: ...

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. Filebased Deploy and Run is not available for use with transactional deployments. The dnrFile has the following associated attributes: „

— 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. location

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: ...

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 directorybased. 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: „

— 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. location

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: ...

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. OpenDeploy references a reverse deployment configuration containing a Deploy and Run

Base server host initiates reverse deployment to reverse source. Files are reverse deployed back to the reverse target. mars (source) (reverse target)

venus (target) (reverse source)

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.

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: \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 nontransactional deployments. Configuration

Transactional

Response Code Behavior



yes no



yes no

Deployment runs regardless, and returns status Completed and code 0. Deployment is aborted, and returns status Failed and code 2.



yes

Not applicable when eventReporting is disabled and infoStreamFormat="log".



Deployment is aborted, and returns status Failed and code 2.

no

yes no yes no



yes



yes no

no

Deployment rolls back, and returns status Failed and code 2. Deployment is aborted, and returns status Failed and code 2. Deployment rolls back, and returns status Failed and code 2. Deployment is aborted, and returns status Failed and code 2. Deployment runs regardless, and returns status Completed and code 0. Deployment is aborted, and returns status Failed and code 2.

225

Deploy and Run

Configuration

Transactional

Response Code Behavior



yes

Deployment rolls back, and returns status Failed and code 2.

no

Deployment is aborted, and returns status Failed and code 2.



yes no



yes no



yes no



yes no

Not supported. Deployment is aborted midstream, and returns status Completed with Errors and code 9. Not supported. Deployment is aborted midstream, and returns status Completed with Errors and code 9. Not supported. Deployment is aborted midstream, and returns status Completed with Errors and code 9. Not supported. Deployment is aborted midstream, and returns status Completed with Errors and code 9.

and

These are both the same trigger points.

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 [email protected]" or cmd="/usr/local/bin/iwperl /path/to/script.pl"

„

where — enter the location to where OpenDeploy must go before executing the script.

For example: where="/tmp"

or

where="C:\temp"

You must use the path syntax supported by your OpenDeploy server. Forward slashes (“/”) can be used for either Windows or UNIX hosts, while backslashes (“\”) are only permitted on Windows hosts. The where attribute is optional. If you do not specify a value, the process takes place in the root directory. „ as (UNIX only) — enter a different user name or user ID under which you will run the script. This option allows you to run the script as a different user. In the following example: as="rroe"

or

as="110"

you can run the script as rroe or its user ID 110 rather than your regular user name. By default, the script runs as the user who invokes the deployment when the base server or receiver is running as root. If the base server or receiver is running as a non-root user, then the script is run as the same user as the base server or receiver process. „ async — indicate whether or not to run the script asynchronously. Exercise caution when using this mode, as it could cause many scripts to be run simultaneously. The output from scripts run asynchronously is not captured. Default value is no.

227

Deploy and Run

In the following example: <script cmd="/bin/sh /usr/local/bin/email_to_admin.sh" where="/tmp" async="yes"/>

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> <pathSpecification> <path name="monthly"/> <deployment transactional="no"> <script cmd="/default/main/dev/scripts" as="webmaster" where="/temp" async="yes"/> <execDeploymentTask useDefinition="webfiles> <deployNRun> <script cmd="email_to_admin.sh" as="webmaster" where="/temp" async="no"/> <script cmd="mail [email protected] < message.txt" as="webmaster" where="/temp" async="no"/> <script cmd="/default/main/dev/scripts" as="webmaster" where="/temp" async="yes"/>

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> <script async="no" cmd="/user/scripts/script_D"/> <script async="no" cmd="/user/scripts/script_C"/> <execDeploymentTask useDefinition="def1"> <script async="no" cmd="/user/scripts/script_A"/> <script async="no" cmd="/user/scripts/script_B"/> ...

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: <profile srcPlatform="UNIX" srcDir="/space/ODadvanced/OpenDeployNG/ solutions/perl" trgPlatform="UNIX" trgDir="/space/ODadvanced/ OpenDeployNG/tmp/viewstream"/>

The following is an excerpt of the same information stream outputted in the log format: ... ...

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> ... ...

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. OpenDeploy references a package deployment configuration. Deployed files are written to a .tar or .zip file.

source (development server)

Package file is copied onto a transportable medium.

Package file is expanded and installed on target.

target (production server)

Figure 3: Package Deployment

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: <script cmd="tar cvf package_file.tar target_area" async="no"/>

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 receiverside 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 parameter 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:

sub-hourly

hourly

daily

weekly monthly

Figure 2: New Schedules Frequency Features ‰

Once — select if the deployment is not recurring.

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 deployments 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: subhourly, 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

„

iwodcmd

„

iwodcmd

„

iwodcmd

— add schedules to deployment configurations. schedget — view scheduling information on a selected deployment. scheddelete — delete existing schedules from deployment configurations. 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 -v -odinst instName deployment

242

Displays help information. Displays version information. Uses OpenDeploy instance instName. Name of the deployment being scheduled.

OpenDeploy Administration Guide

Scheduling from the Command Line

-r -s [N][m|h|d|w]

-e [N][m|h|d|w]

n m h d w -c comment

-inst instance

-k key=value

Repeat every N minutes,

hours, days, or weeks. Time from current time to use as start date. The default is 1 minute from current time when the command is entered. Amount of time from current time to use as end date. The default end time is none. The scheduled deployment will continue indefinitely. A numerical value. Minutes. Hours. Days. Weeks. Description of the deployment being scheduled. See “Use of Comments” on page 244 for more information. 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. 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 business report"

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 -v -odinst instName -a -d deployment -o deployment deployment -j ID

Displays usage information. Displays usage information. Uses OpenDeploy instance instName. Gets all schedules. This is the default option. Gets all schedules for a particular deployment. Gets one schedule. Requires the deployment name and the deployment ID number. The name of the deployment configuration. 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 -v -odinst instName deployment -j ID

"dep_name_pattern*"

Displays usage information. Displays version information. Uses OpenDeploy instance instName. The name of the deployment configuration. 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. 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 -v -odinst instName -a deployment -a "dep_name_pattern*"

-d deployment -d "dep_name_pattern*"

deployment -j ID

Displays usage information. Displays version information. Uses OpenDeploy instance instName. Activates a specific scheduled deployment. 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. Deactivates a specific scheduled deployment, using the deployment and -j ID options. 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. The name of the deployment configuration. 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 commandline 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 browserbased 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 Time API: 2001-11-12 13:09:55 PST GMT-08:00 Using locale: en_US API: 2001-11-12 13:09:55 PST GMT-08:00 Using OpenDeploy home directory: C:\INTERW~1\OPENDE~1 API: 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.xml API: 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.xml API: 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.jmoorebw2k ENG: 2001-11-28 13:06:12 PST GMT-08:00 Got converted config for .monthly.MYDEFINITIONNAME.jmoorebw2k ENG: 2001-11-28 13:06:12 PST GMT-08:00 Waiting for 2 children to complete phases ENG: 2001-11-28 13:06:12 PST GMT-08:00 All 2 children completed their phases ENG: 2001-11-28 13:06:12 PST GMT-08:00 Deployment[monthly] Elapsed Time=120 ms ENG: 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 displayed 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 window 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: „

— 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. deployment

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 : 0 Directories failed : 0 Files failed : 0 Links failed : 0 Directories deleted : 0 Files deleted : 0 Links deleted : 0 id=0 server: File Content transferred: 4647780 bytes id=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.sourceserver.to.target-server.log

where the following variables apply: „

— 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. deployment

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 displaying 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: „

— 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. deployment

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:

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:

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: „

— verbose „ maxBytes — 32 mb „ directory — od-home/(od-instance)/log

264

level

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: „ „ „ „ „ „

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. hostname_database.log —

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 ClearCase CVS Email Example delivery FTP Generic delivery Microsoft COM Microsoft Global Assembly Cache Microsoft Application Center Microsoft Visual Source Save (VSS)

bbl

MKS PVCS WebLogic Application server WebSphere Application server WebSphere Portal target

mks

cc cvs email exmpld ftp gen mscom msgac msac vss

pvcs wlas wsas wspsd

269

Logging

Adapter

Adapter Name

WebSphere Portal source

wspsp

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.

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 userdefined 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> ... <eventReporting enabled="yes" cfgPath="C:\Interwoven\OpenDeployNG\etc\eventReportingConfig.xml"/>

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> <process name="OpenJMS" startCommand="MYOPENDEPLOYSHORT/jre/bin/java -Xmx256M -Xms64M -Dopenjms.home=MYOPENDEPLOYSHORT/openjms -Djava.security.manager -Djava.security.policy=MYOPENDEPLOYSHORT/ openjms/config/openjms.policy -Djava.rmi.server.codebase=file: MYOPENDEPLOYSHORT/openjms/lib/openjms-client-0.7.6.1.jar -Djava.rmi.server.useCodebaseOnly=true ${OPENJMS_RMI_PORTS} -classpath ${OPENJMS_CP} org.exolab.jms.server.JmsServer -config MYOPENDEPLOYINSTSHORT/etc/jmsConfig.xml" stopCommand="MYOPENDEPLOYSHORT/jre/bin/java -Dopenjms.home=MYOPENDEPLOYSHORT/openjms -Djava.security.manager -Djava.security.policy=MYOPENDEPLOYSHORT/openjm/config/ openjms.policy ${OPENJMS_RMI_PORTS} -classpath ${OPENJMS_CP} org.exolab.jms.tools.admin.AdminMgr -config MYOPENDEPLOYINSTSHORT/ etc/jmsConfig.xml -stopServer" startDir="MYOPENDEPLOY/openjms"> <environment name="OPENJMS_CP" value="MYOPENDEPLOYSHORT/lib/ hsqldb.jar"/> <environment name="OPENJMS_CP" value="${OPENJMS_CP}: MYOPENDEPLOYSHORT/openjms/lib/openjms-0.7.6.1.jar"/> <environment name="OPENJMS_RMI_PORTS" value="-DRmiPort1=${JMS_RMI1} -DRmiPort2=${JMS_RMI2} -DRmiPort3=${JMS_RMI3} -DRmiPort4=${JMS_RMI4} -DRmiPort5=${JMS_RMI5} -DRmiPort6=${JMS_RMI6} -DRmiPort7=${JMS_RMI7} -DRmiPort8=${JMS_RMI8}"/> <jndiContext initialContextFactory="org.exolab.jms.jndi. InitialContextFactory" url="tcp://MYHOSTNAME:MYJMSJNDIPORT/" classpath="MYOPENDEPLOYSHORT/openjms/lib/openjms-client0.7.6.1.jar:MYOPENDEPLOYSHORT/openjms/lib/exolabcore-0.3.7.jar"> <property name="useLog" value="openDeployPublisherLog"/> <session transactional="false" acknowledgeMode="CLIENT_ACKNOWLEDGE">

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> ...

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. <property name="user" value="sa" /> <property name="password" value="" />

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 JDBCcompliant 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. ...

This element contains the following attributes that are used to specify information related to the reporting server’s connection: „

„ „

„ „

— 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. hostName

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: ...

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: ... <process ...> ...

The process element defines a series of sub-process command attributes associated with the reporting feature: „

— denotes the unique name of the process element. „ startCommand — specifies the command-line tool used to start the sub-process. For example: name

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 subprocess. For example: stdin="passwd"

„

stdout —

specifies the absolute path to a file in which to write the output of the subprocess. 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 .../>
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}"

„

— 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. obscured

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: <property name="user" value="sa"/> <property name="password" value=""/>

If you wanted to use IBM DB2, you would comment out the default (Hypersonic) database element, and uncomment the following database element:

5. Replace the parameter variables in the database element you want to use, such as USERNAME and PASSWD with the appropriate actual values. See “Configuring Your Database” 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 location: 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:

283

Reporting

<property name="user" value="sa"/> <property name="password" value=""/>

If you wanted to use IBM DB2, you would comment out the default (Hypersonic) database element, and uncomment the following database element:

14. Replace the parameter variables in the database element you want to use, such as USERNAME and PASSWD with the appropriate actual values. See “Configuring Your Database” 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 location: 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: ... <property name="user" value="sa"/> <property name="password" value="123ABC"/> ...

The database element contains the following required attributes that you must configure: „

— this value is fixed as ReportingDB. „ className — specify the class name of the JDBC driver class to load. For example: name

className="org.hsqldb.jdbcDriver"

285

Reporting

„

— specifies the JDBC connection string (URL) to use to connect to the database. For example: connectionString

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: <property name="user" value="sa"/> <property name="password" value="123ABC" obscured="true"/>

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. to generate the encoded string. Refer to Use the “iwodpasscoder” on page 40 in the OpenDeploy Reference for more information on this tool. Default value is false. iwodpasscoder program

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 “Deleting 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 following tags with the specified value: ‰ [DBTYPE] — hsqldb 288

OpenDeploy Administration Guide

Administration Server Configuration for Reporting

‰ ‰ ‰ ‰ ‰

— SA [DBPASSWORD] — (leave blank) [DBSERVER] — controlhub [DBNAME] — (leave blank) [DBPORT] — 9001 [DBUSER]

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.sql iwoddbtool.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-to602_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: ...

The odNode element has the following associated attributes: „

— 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: host

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: ...

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-andforward 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: „ „ „ „ „ „

298

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

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

302

„

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

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 Deployment 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 configuration 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. Report Type

Description

Associated Properties

Displays all workflows which „ Workflow have completed within the given time. Published Editions Displays all editions published „ Store within the given time period. „ Branch Content Submission Displays all submits that „ Branch occurred within the given time „ Area period. „ User ID Files Owned by Active Displays all the active tasks with „ Branch Task the files associated with them. New Active Jobs Displays all the active (not „ Workflow completed) jobs in the given „ Task Area VPath (from where date range. the workflow job was started)

Completed Jobs

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.

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 information: ‰ 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:

317

Encryption

Using Symmetric Encryption with Reverse Deployments If you are performing a reverse deployment using symmetric key encryption, you must include the path to the symmetric key file residing on the reverse source (normally the receiving server in a forward deployment) in the deployment configuration. This is the same location as specified in the base server or receiver configuration file of the reverse source. This differs from a forward deployment, where the configuration would include the path to the key file where it resides on the source. The deployment configuration must include the path syntax of the reverse source. The path to the symmetric key file is defined in the keyFile attribute of the localNode element. In the following example, the source mars has the base server software installed and is running on UNIX. The target venus has the receiver software installed and is running on Windows. In a typical forward deployment using symmetric key encryption, the localNode element in the deployment configuration residing on mars would be:

and the localNode element in venus’ receiver configuration file would be:

In a reverse deployment involving these two servers, the localNode element in the reverse deployment configuration would be:

and the localNode element in the base server configuration file on mars would be:

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 multistep 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: Windows

UNIX

openssl.exe

openssl

openssl.cnf

openssl.cnf

CA.bat

CA.sh

„

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.

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 following 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) []:Interwoven Organizational Unit Name (eg, section) []:Engineering Common Name (eg, YOUR name) []:Engineering Certificate Authority Email 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 „ UNIX — CA.sh -newca -days 200

200

or

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 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) []:Interwoven Organizational Unit Name (eg, section) []:Engineering Common Name (eg, YOUR name) []:Receiver certificate Email 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 certificate/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 configured. 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 thirdparty CA's certificate. For example: 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: „

— 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. sslCertificate

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:

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:

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: „ „ „ „ „ „ „ „ „

330

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.

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

‰

EDH-RSA-DES-CBC3-SHA

‰

DES-CBC3-SHA

SSLversion 2 or version 3 „ High-strength (168 bit) ciphers:

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:

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:

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:

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 OpenDeploy” 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 thirdparty CA's certificate. For example: 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: „ „ „

„ „ „

340

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.

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:

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) 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

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: „

„

„

„

„

„

366

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.

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:

372

„

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.

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 readonly 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 XMLbased 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: ‰

‰

‰

— requests the target host to get its OpenDeploy version and sends it back to the sender. IW_GET_REMOTE_VERSION

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 userdefined, 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 browserbased 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:

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) 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

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: „ „ „ „ „

404

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.

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: „

406

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.

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 commandline 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. <source> <payload area="/default/main/branch1/STAGING"> <pathSpecification> <path name="."/> <payLoadRules> <predicate operator="CONTAIN" value="Title">

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 userdefined 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 browserbased 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> <nodeRef useNode="MyLocalHost"/> <schedule> <startTime year="2004" month="02" day="02" hour="12" minute="00"/> <description>This is a monthly syndication of finanacial reports <endTime year="2004" month="14" day="15" hour="18" minute="00"/>

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> ... ...

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> <nodeRef useNode="MyLocalHost"/>

The opendeploy element contains the transactional attribute.

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: „ „ „ „

„ „

— 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. logRules

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>

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:

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: „ „ „ „ „ „

— 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. ftp

The ftp element contains the following attributes: „ „ „ „ „ „

— 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. name

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

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]"/> ...

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: „

— 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. name

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: „

— 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. parameters

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"/> ...

The startTime element contains the following attributes: „

year

— specify the four-digit year value, for example:

year="2004"

„

— specify the two-digit month (01-12) value. For example, the month April would be specified as: month

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"/> ... ...

If you want the deployment to only occur once, include the once element within the frequency element:

If you want the syndicated deployment to occur multiple times, include the discrete element within the frequency element: ...

The discrete element’s interval attribute specifies the number of time periods (specified later in this section) between syndicated deployments, for example:

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:

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: „

— defines the time interval (hour, day, week, and so on) the deployment occurs. „ endTime — defines the timeframe when the deployment will no longer occur. type

... <endTime ... />

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

„

hourly

„

daily

„ „

weekly

(minutes)

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: <sub-hourly/> <endTime ... />

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

or

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: <weekly weekday="wed"/>

418

OpenDeploy Administration Guide

Command-Line

The weekday attribute supports the following values: „ „ „ „ „ „ „

— Monday tue — Tuesday wed — Wednesday thu — Thursday fri — Friday sat — Saturday sun — Sunday mon

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: <montyly monthDays="1,15"/>

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. ... <endTime ... />

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> <nodeRef useNode="MyLocalHost"/> <definition name="MYDEFINITIONNAME"> <source> <payload area="/default/main/branch1/STAGING"> <pathSpecification> <path name="."/> <payLoadRules> <predicate operator="CONTAIN" value="Title"> <deployment transactional=""> <execDeploymentTask useDefinition="MYDEFINITIONNAME"/>

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 subscriptiondelete command-line tools, respectively.

offerdelete

and iwodcmd

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.

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. Client Application

WSDL SOAP Listener Web services API Base server or receiver

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.

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.

Client Application

SOAP 2. Request authentication

ContentServices Foundation Access Service

1. Collect user credentials

3. Authenticate user and return object.

5. Validate user object and check authorization rule.

SOAP 4. Request start deployment.

ContentServices for OpenDeploy

6. Start deployment

Base Server

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.

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: and

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 pending.

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 window. 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 -v -l -b branchVPath -r branchVPath -lae branchVPath

Displays usage information. Displays version information. Gets archival policies for all branches. Gets archival policy for a specified branch. Starts archival run for a specified branch. 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 Email Network Appliance NetCache BEA WebLogic 8 Application Server BEA WebLogic 9 Application Server IBM WebSphere Application and Portal Servers BEA bulk loader Microsoft (included with OpenDeploy on Windows only): ‰ Application Center ‰ COM+ ‰ Global Assembly Cache (GAC) Provisioning Sun Content Infrastructure System (SunCIS)

See “Utilizing the Delivery Adapter Framework” on page 208 for information on how delivery adapters are used. Note: Use of delivery adapters with EasyDeploy is not supported.

Generic Delivery Adapter OpenDeploy includes a generic delivery adapter capable of invoking external programs on deployment or rollback. For example, scripts that apply and roll back database configuration changes can be deployed to a target server and then automatically executed by the generic delivery adapter at the appropriate times.

439

Delivery Adapters

Adapter Configuration The generic delivery adapter requires the presence of an associated XML-based configuration file. This configuration file contains the settings to run the generic delivery adapter. The generic delivery adapter configuration file can reside anywhere on the target host. You must specify the full path to this file in the deployment configuration file, which is explained in the following section. The following is an example of this configuration file: <deploy cmd="c:\Interwoven\OpenDeployNG\your_deploy_script"/>

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: „

— defines a deployment task. „ rollback — defines a rollback task. deploy

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:

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: „ „ „ „ „ „

— 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. Host

441

Delivery Adapters

For example: Host=mars.mycompany.com Port=21021 User=jdoe Password=123abc TargetDir=/website/files ConnectionMode=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:

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] Host=mail.mycompany.com Subject=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:

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.

edge server content deployed from source to target

source host

content redeployed to edge servers using HTTP

edge server

target host/ origin server for NetCache devices

edge server

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

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: <serverSet> <server host="andromeda" port="3132" userid="jdoe" password="aBcDeF321" isPasswordEncrypted="yes" webServerName="NYweb1" logFile="/dir/logfile.txt">

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: „ „ „ „ „ „ „

— 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. host

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:

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 -v -m manifest_file

-p config_file

446

Displays help information. Displays version information. Specifies the absolute path to the manifest file. If a full path is not specified, the default directory is od-home/(od-instance)/log. Specifies the absolute path to the NetCache configuration file.

OpenDeploy Administration Guide

Network Appliance NetCache Adapter

-s source_area -d od_home

Specifies the content source area for the deployment to the NetCache edge servers. Specifies the OpenDeploy home directory (odhome).

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: <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:
Note the use of three slashes (“///”). The WebLogic 8 configuration file contains the container element weblogic. Within weblogic are the following child elements:

448

„

admin

„

action

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. „ „

„ „

„ „

„

— 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. password

The action element contains the following attributes for configuring deployment activities: „

— 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.

name ‰ ‰ ‰

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

„

— 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). stage

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:

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: <WLAppServer xmlns="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"> <userCredentials userName="weblogic" password="weblogic"/> <deploy targets="examplesServer" deploymentName="exampleServerName" explodedFormat="true"/>

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:

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

452

customTrustKS

-Dweblogic.security.CustomTrustKeyStoreFileName= {filename} -Dweblogic.security.TrustKeystoreType=CustomTrust

protocol server port

-adminurl

userName

-username username

password

-password password

[protocal://]server:port

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: <websphere> <wsadmin exec="C:\PROGRA~1\WebSphere\DeploymentManager\bin\ wsadmin.bat"/> "{-contextroot /dir1/dir2 -distributeApp -installdir c:/temp -nopreCompileJSPs}"

453

Delivery Adapters

You must update the DOCTYPE to include the full path to the WebSphereAppServer.dtd on your host using the following syntax:
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: „ „

„

„

„

„

— 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. exec

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: „

— 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. name

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 "{-contextroot /dir1/dir2 -distributeApp -installdir c:/temp -nopreCompileJSPs}"

Ensure that all the options are in the JACL list (enclosed in the curly braces (“{}”)). You must also enclose the list with double quotes. Portal Server

The following is an example of the portal server configuration file: <websphere> <portal> <xmlaccess exec="websphere-home\xmlaccess.bat" userName="username" password="password" passwordEncoded="yes" host="hostname" port="9081" filename="configFileName"/>

455

Delivery Adapters

You must update the DOCTYPE to include the full path to the WebSphereAppServer.dtd on your host using the following syntax:
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: „ „ „ „

„ „ „

456

— 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. exec

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:

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:

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:

You must update the DOCTYPE to include the full path to the BEABulkLoader.dtd on your host using the following syntax:
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: „

458

BEABulkLoader element — defines the container for the configuration file.

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"

‰ ‰ ‰

‰ ‰

— 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. appName

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:

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: <MSAppCenter exec="C:\AC2000SP2\program files\Microsoft Application Center\ac.exe"> MyACDeployment <Source> jdoe-pc odwin1 odwin2 <Applications> <ApplicationName>application1 <ApplicationName>application2

You must update the DOCTYPE to include the full path to the MSAppCenter.dtd on your host using the following syntax:
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: „

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: MSAppCenter

exec="C:\AC2000SP2\program files\Microsoft Application Center\ac.exe"

„

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. ACDeploy

461

Delivery Adapters

„

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.

„

„

„ „ „

„ „ „

DeploymentName

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:

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: <MSCOM>

You must update the DOCTYPE to include the full path to the MSCOM.dtd on your host using the following syntax:
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

„

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. COMPLUSApplication

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:

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:

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: <MSGAC gacutilPath="c:\vstud_dotnet\FrameworkSDK\Bin\ gacutil.exe">

You must update the DOCTYPE to include the full path to the MSGAC.dtd on your host using the following syntax:
Note the use of three slashes (“///”). Here is a description of the elements and attributes associated with the Microsoft GAC adapter configuration file: „

468

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. MSGAC

OpenDeploy Administration Guide

Microsoft Global Assembly Cache (GAC) Adapter

„

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. GlobalAssembly

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:

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 element with the following odAdapter element:

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>

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.html C:\website\files\www\andre\index.html C:\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"/>

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_DRIVER url=URL, user=USER, password=PASSWORD" logLevel="level"/>

The adapter translates the query into a SQL call and returns a manifest of files matching the query. Use this database adapter when you are specifying your query as PCDATA within the payLoadRules element in the deployment configuration file. For the parameter attribute, the following name-value parameter pairings are required for these adapters: „ „ „ „ „ „

— 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. driver

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> <custom>od-home/adapters/payload/scm/clearcase/conf/ ClearCaseUpdateConfig.xml

The following examples show each type of configurations.

Checkout Command

Update Command

You must update the DOCTYPE to include the full path to the ClearCaseScm.dtd on your host using the following syntax:

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

‰

— 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. log

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> <custom>od-home/adapters/payload/scm/vss/conf/ VssGetConfig.xml

The following examples show each type of configurations.

Checkout Command

Get Command

You must update the DOCTYPE to include the full path to the ClearCaseScm.dtd on your host using the following syntax:

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> <custom>od-home/adapters/payload/scm/ conf/PvcsGetConfig.xml

The following sample demonstrates shows this configuration:

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:

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> <custom>od-home/adapters/payload/scm /conf/CVSCheckoutConfig.xml

The following sample demonstrates shows this configuration:

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:

486

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 catModule force local doNotExecuteCheckout checkoutToStdOut catModuleWithStatus revision date checkoutToDir

-R -c -f -l -n -p -s -r tag -D date -d dir

useKOption mergeRev1

-k kflag -j revision

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> <custom>od-home/adapters/payload/scm/ conf/MKSResyncConfig.xml

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>

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

488

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

OpenDeploy Administration Guide

Software Configuration Management Adapters

Attribute

Option

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

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”>

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> <custom>od-home/adapters/payload/ WebSpherePortalConfig.xml

The following is an example of an IBM WebSphere Portal payload adapter configuration file. <websphere> <portal> <xmlaccess exec="c:\ibmtool\xmlaccess.bat" userName="portaladmin" password="password" passwordEncoded="no" host="hostname" port="9081" filename="c:\ibmtool\export.xml" outputfile="C:\Interwoven\OpenDeployNG\userlib\orion_out.xml"/>

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:

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: „ „ „ „

„ „ „

— 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. exec

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 The practice of starting a deployment, but not waiting for the deployment 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 An XML-based file that defines the rules and settings for a base configuration file 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 certificate

The initial Administrator role user identity used to assign the Administrator role to other individuals. 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 An OpenDeploy deployment configuration that simply contains a file 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

Deploy and Run deploy server configuration DTD deployment deployment configuration

494

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. An OpenDeploy feature that allows external scripts or programs to be integrated into the deployment process. The XML-based DTD upon which the base server and receiver configuration files is derived. The moving of files from a source host to one or more target hosts based on a particular deployment configuration. A combination of elements and attribute values which define the criteria for if and how files are to be deployed.

OpenDeploy Administration Guide

deployment An XML-based file that defines the rules and settings for a source configuration file 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 A type of deployment configuration where an area on the source and comparison 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 A configuration file residing on each base server or receiver that configuration file 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 log files log format logging level logical host name macro deployment log manifest format micro deployment log multi-host installation multi-tiered deployment multi-tiered transactional deployment node node configuration file normal logging level parameter substitution

path path-based filter

pattern-based filter

payload adapterbased deployments

496

The movement of deployed files from a sending host to a specific target. Files containing information related to the status of the OpenDeploy server or a particular deployment. A legacy format used to organize the information stream data. One of the choices that determines the amount and type of logged information regarding deployments. A name mapped to a host’s name or IP address that is used to identify that host in configurations. The log file containing entries related to the activities involving a deployment configuration. An XML-based format used to organize the information stream data. The log file containing entries related to the activities involving each individual source/target pairing of a deployment. The installation of all the required OpenDeploy software components on multiple servers in some combination. A deployment configuration where deployed files are received by an OpenDeploy base server host and then redeployed across tiers. A multi-tiered deployment in which the deployment transaction spans all servers. A host that can send or receive files. An XML-based configuration file that defines all the target hosts for a source host. A logging level that logs standard status and error messages. 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. An element that further defines a specified file system location or TeamSite area. 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. 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 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 Administration Guide

permission rules physical host name pre-commit phase

previous area

primary area

production server quick report quorum receiver receiver log receiver macro deployment log receiver micro deployment log recurring deployment reporting reporting management configuration file reporting server

Optional directives to apply to the deployed files or directories on the target host. The name or IP address of a host. 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. 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. 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. Typically, a host with content that is accessible either on an intranet or the Internet. A predefined query that can be accessed and run at any time without any additional report configuration required. The specified minimum number of successful legs in a transactional deployment for the overall deployment to be considered successful. A host on which OpenDeploy receiver software is installed. A receiver can only receive deployed files from a source host. A log file containing entries related to the receiver host. A log generated by the receiving host that contains information for the received deployment. A log generated by the receiving host that contains information regarding a specific source/target pairing in a deployment. A scheduled deployment where the deployment repeats on a regular basis, such as daily or weekly. The collection and displaying of deployment information that is managed by the reporting server in a central database. A configuration file used by the reporting server to subscribe to deployment events from base server and receiver hosts.

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 A deployment that is performed at a predetermined time and date. deployment 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 A configuration file located on an OpenDeploy server with the base file 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 A deployment where no files are moved, but entries are made in the deployment 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 The installation of all the required OpenDeploy software installation components on a single server. source host A host with base server software installed and licensed that can deploy and receive files. source macro A log generated by the sending host that contains information for deployment log the sent deployment. source micro A log generated by the sending host that contains information on a deployment log 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 A deployment that either successfully moved the deployed files to all deployment of its intended targets, or at least to the number of targets specified by the quorum value. symmetric key A lower level (40-bit) of encryption you can assign to deployed files. encryption

498

OpenDeploy Administration Guide

synchronized deployment target host

The distribution of file and database assets together using OpenDeploy and DataDeploy in a single deployment transaction. 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 A deployment configuration where two TeamSite areas are compared comparison 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 A feature which restores one or more targets to their previous deployment 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 A ACDeploy element 461 ACEs perm bits 198 standard perms 199 types 198 ACLs 189, 198 ignoring vs. preserving 199 names 198 UNIX deployments 200 action element 129, 449, 455 adapters 381 delivery 208, 211, 439 logging 269 Network Appliance NetCache 444 parameter substitution 206 payload 471 address attribute 415 admin element 449 administration server logging 268 reporting 276 Administrator role 71, 73 adminurl attribute 449, 459 allowBranching attribute 484 allowDnrExecution attribute 233 allowedDirectories element 28 allowedHosts element 28 allowMultiLock attribute 484 altappdd attribute 450 altwlsappdd attribute 450 amask attribute 193 and element 128 append attribute 275 application element 454 ApplicationGUID attribute 462 ApplicationName attribute 462 Applications element 462 applyExtAttrs attribute 113 applySourceFileTime attribute 191 appName attribute 449, 455, 459 appsvr element 454

Archival module 431 ControlHub 432 editions, selecting 435 installation 432 OpenDeploy, standalone 431, 470 policies 434 scheduled 436 area (areaDiff) attribute 108 area (payload) attribute 123 area (targetFilesystem) attribute 105, 112 area (targetRules) attribute 140 area (targetTeamsite) attribute 112 area (TeamSite) attribute 110 area attribute 94 areaDiff element 94, 108 areas alternate target 140 file system-based 112 TeamSite-based 112 as attribute 227 assemblyDLLName attribute 469 assemblyName attribute 469 AssemblyNameToUninstall element 469 async attribute 210, 227 asynchronous deployments 70 attemptAppDeleteOnDLLDelete attribute 466 attribute currenttime 477 keywords 82 preservetime 477 syntax 81 types 81 attributes address 415 adminurl 449, 459 allowBranching 484 allowDnrExecution 233 allowMultiLock 484 altappdd 450 altwlsappdd 450 amask 193 append 275 501

ApplicationGUID 462 ApplicationName 462 applyExtAttrs 113 applySourceFileTime 191 appName 449, 455, 459 area 94 area (areaDiff) 108 area (payload) 123 area (targetFilesystem) 105, 112 area (targetRules) 140 area (targetTeamsite) 112 area (TeamSite) 110 as 227 assemblyDLLName 469 assemblyName 469 async 210, 227 attemptAppDeleteOnDLLDelete 466 autoResponse 480, 481, 483 baseDirectory 459 baseProject 483 blockCheckInterval 88 blockMaxWaitTime 88 branch 477 bufferSize 196 byteIncremental 191 cfgPath 272 changeAccess 190, 194 checksumCompare 188 checksumVerify 191 class (odAdapter) 210 class (payLoadProperties) 124 className 285 cmd (deploy) 440 cmd (rollback) 440 cmd (script) 227 comment 477, 480 commentFile 477 compression 191, 192 compressionLevel 191, 192 ConnectionMode (FTP adapter) 441 connectionString 286 daily 418 date 480, 481 dateDifferent 188 dateTime 484 day (endTime) 419 day (startTime) 416 debug 294 deployment 151 502

deploymentDir 466 description 469 directory 193, 251, 264 doDeletes 120, 178, 190 dontDo 190 enabled 272 exec (ODMSAppCenterConfig) 461 exec (wsadmin) 454 exec (xmlaccess) 456, 491 execPath (clearcase) 476 execPath (pvcs) 483 execPath (vss) 480 explodedFormat 449 file 193 filename 454, 456, 491 fileNewerThan 484 filePath 118 fileTimestamp 480, 481 fileUseCurrentTime 484 followLinks 201 force 469 format 127 from 195 From (email adapter) 443 fromNode 163 gacutilPath 468 group 193 Host (email adapter) 443 Host (FTP adapter) 403, 441 host (ftp) 414 host (localNode) 86 host (odNode) 294 host (server) 445 host (wsadmin) 454 host (xmlaccess) 456, 491 hostName 277 hostRmiPort 277 hour (startTime) 416 hourly 418 ID 466 id 469 ignoreAcls 188, 199 ignoreGroup 188 ignoreModes 188 ignoreUser 188 instanceName (schedule) 416 invokeOnSuccess 151 isEventDLL 466 isPasswordEncrypted 445 OpenDeploy Administration Guide

itemPath (clearcaseItem) 478 itemPath (pvcsItem) 484 itemPath (vssItem) 481 key (request) 388 keyFile 317, 318 label 480, 481 level 264 loaderClassPath 459 localPath 480, 483 location (dnrDeployment) 220 location (dnrDeploymentJob) 217 location (dnrDir) 223 location (dnrFile) 222 lock 483 lockTimeout 446 log 478 logFile 445 logLevel 124, 210 mask (dnrDir) 223 mask (dnrFile) 222 maxAge 446 maxBytes 263, 266 minAge 446 minute (endTime) 420 minute (startTime) 416 month (endTime) 419 month (startTime) 416 monthDays 419 multiTierTransactional 151, 152 name (action) 129, 449, 455 name (clearcase) 476 Name (COMPLUSApplication) 466 name (database) 285 name (DLL) 466 name (email) 415 name (environment) 279 name (external) 89, 92 name (ftp) 414 name (internal) 89 name (key) 127 name (localNode) 163 name (log) 275 name (odAdapter) 210 name (path) 104 name (payLoadProperties) 124 name (process) 278 name (Property) 466 name (property) 286 name (pvcs) 483

name (replicationFarm) 90 name (routeDefinition) 162 name (transportProperties) 196 noData 477 node 454 nologo 469 nostage 450 noWarn 477 obscured (environment) 279 obscured (property) 286 omask 193 operator 126 output 480, 481, 483 outputfile 491 override 484 overwrite 477 parameter (email) 415 parameter (ftp) 414 parameter (odAdapter) 210 parameter (payLoadProperties) 124 parameterNS (custom) 125 parameterNS (deploymentConfiguration) 83 parameterNS (odAdapter) 210 parameters (schedule) 416 password (admin) 449 password (Credential) 462 Password (FTP adapter) 403, 441 password (ftp) 414 password (load) 459 password (pvcsGet) 483 password (server) 445 password (vssCheckout) 480 password (vssGet) 480 password (wsadmin) 454 password (xmlaccess) 456, 491 passwordEncoded 449, 461, 483 passwordEncoded (load) 459 passwordEncoded (vssCheckout) 480 passwordEncoded (vssGet) 481 passwordEncoded (wsadmin) 454 passwordEncoded (xmlaccess) 456, 491 path 275 Port (FTP adapter) 441 port (odNode) 294 port (server) 445 port (wsadmin) 454 port (xmlaccess) 456, 491 preserveAcls 190, 194, 199 preserveTime 477 503

previousArea 60, 107, 108, 109, 110, 111 projectDB 483 projectPath 483 promotionGroup 484 proxyStubDLL 466 publisher 277 pwd (wsadmin) 454 quorum 148 recordExtAttr 114 recursive 480, 481, 483 regex (exceptPattern) 184 regex (excludePattern) 182 regex (includePattern) 180 rename 477 repositoryType 459 reserved 477 respository 459 restartMarker (odReportingConfiguration) 277 revert 188 revision 484 rmReadOnly 191 roundRobbin (odReportingConfiguration) 277 scheme 469 serverClusterFlag 454 serverPath 480 setAccess 190, 194 silent 469 sourceAccessibility 449 sslCaCertificate 329 sslCertificate 329 sslCiphers 330 sslPrivateKey 329 sslVerifyPeer 329 stage 450 startAppFlag 455 startCommand 278 startDir 279 state (dnrDeployment) 220 state (dnrDeploymentJob) 217 state (dnrDir) 223 state (dnrFile) 222 stderr 279 stdin 279 stopCommand 278 stout 279 sub-hourly 418 Subject (email adapter) 443 subPath (exceptPath) 183 subPath (excludePath) 181 504

subPath (includePath) 179 svrOrClusterName 454 svrTryCount 191 svrTryDisableOverwrite 191 svrTryInterval 191 target 449 TargetDir (FTP adapter) 403, 441 targetDir (ftp) 414 targetFollowLinks 119 timeout 87 tmpDir (emailSet) 415 tmpDir (ftpSet) 414 to 195 To (email adapter) 443 toNode 163 transactional 100, 147 transactional (opendeploy) 413 transactional (routedDeployment) 166 triggerPoint 220 type 127, 466 typeLibrary 466 unsubscribed 294 useDefinition 147 useNode 90, 147 User (FTP adapter) 403, 441 user (ftp) 414 user (permissionRules) 193 userconfigfile 449 userId 483 userid 445 userkeyfile 449 userName 449 userName (load) 459 userName (vssCheckout) 480 userName (vssGet) 480 userName (wsadmin) 454 userName (xmlaccess) 456, 491 useRouteClass 166 useRouteDefinition 166 useServerNodeHost 166, 167, 356 value (environment) 279 value (predicate) 127 value (Property) 466 value (property) 286 version (clearcaseCheckout) 477 version (MSCOM) 465 version (MSGAC) 468 version (ODMSAppCenterConfig) 461 version (odNode) 294 OpenDeploy Administration Guide

version (pvcsGet) 484 version (vssCheckout) 480 version (vssGet) 481 weblogicJar 449 webServerName 445 weekday 418 when (dnrDeployment) 220 when (dnrDeploymentJob) 217 when (dnrDir) 223 when (dnrFile) 222 where 227 workSpace 483 writable 481, 484 writableFiles 481 writableFiles (vssCheckout) 480 year (endTime) 419 year (startTime) 416 autoResponse attribute 480, 481, 483 B bandwidth throttling 196 base server logging 254, 267 reporting 272 starting 20 base server configuration file 38 reporting 272 base server log file 36, 254 recovery 267 baseDirectory attribute 459 baseProject attribute 483 BEA bulk loader adapter adapter configuration 458 BEA bulk loader adapters 458 deployment configuration 460 BEA WebLogic 8 adapter 448 BEA WebLogic 9 adapter 451 BEABulkLoader element 458 blockCheckInterval attribute 88 blockMaxWaitTime attribute 88 bootstrap administrator 32 branch attribute 477 browsers, refresh 29 bufferSize attribute 196 byteIncremental attribute 191 C cacheProperties element 446 cancellation, deployments 60

certificate authority expiration 323 setup 321 third-party 325 certificates expiration 325 generation 323 verification 327 cfgPath attribute 272 changeAccess attribute 190, 194 checksumCompare attribute 188 checksumVerify attribute 191 ciphers 330 default 331 high-strength 331 low-strength 331 no-authentication 331 types 331 class (odAdapter) attribute 210 class (payLoadProperties) attribute 124 className attribute 285 clearcase element 476 clearcaseCheckout element 477 clearcaseItem element 478 clearcaseUpdate element 477 cmd (deploy) attribute 440 cmd (rollback) attribute 440 cmd (script) attribute 227 command-line tools iwodauthorize 76 iwodcmd archive 437 iwodcmd schedactivate 249 iwodcmd schedadd 242, 244 iwodcmd scheddelete 247 iwodcmd schedget 245 iwodcmd serverreset 28, 29 iwodcmd serverstatus 48 iwodcmd start 67, 68 iwodnetcache 446 iwodnonroot 24 iwodservergetversion 47 comment attribute 477, 480 commentFile attribute 477 comparison rules 187, 375 date-based 189 comparisonRules element 187, 188 COMPLUS element 462 COMPLUSApplication element 466 Component element 466 505

Components element 466 compression 192 compression attribute 191, 192 compressionLevel attribute 191, 192 concurrency management 88, 344 configuration files base server 38 host reporting 273 nodes 38 receiver 38 reporting management 276 schedule 425 connection timeout 87, 344 ConnectionMode (FTP adapter) attribute 441 connectionString attribute 286 ContentServices for OpenDeploy 427 ControlHub custom reports 307 events database 280 Credential element 462 currenttime attribute 477 custom element 125 custom reports 297 downloading 304 exporting to SQL 300 generating 300 queries 298, 299 saving as quick report 305 CVS adapter 485 configuration 485 D daemons 19 resetting 28 daily attribute 418 DAS custom reports 305 data asset deployments 135, 138 database auto-synchronization 135 standalone database 136 target-side database deployments 137 database auto-synchronization 135 Database Deployment for OpenDeploy Administration Guide 15 database element 285 databaseDeployment element 214 DataDeploy module 214 DataDeploy wrapper files 384 date attribute 480, 481 dateDifferent attribute 188 506

dateTime attribute 484 day (endTime) attribute 419 day (startTime) attribute 416 debug attribute 294 definition element 93, 146, 147 definitions 93, 100 file filters 99 file rules 99 source file location 93 target file location 97 types 357 Delivery Adapter Framework 208 delivery adapters, writing 211 delivery adapters 208, 211, 439 BEA bulk loader 458 BEA WebLogic 8 448 BEA WebLogic 9 451 configuring 210 email 442 FTP 441 generic 439 IBM WebSphere 453 JDK requirements 212 logging 269 Microsoft application center 460 Microsoft COM+ delivery 464 Microsoft global assembly cache provisioning 468 sample 213 targets 211 delivery element 412 Deploy and Run 101, 215, 349 deleting 356 deployment-based 220, 354 deployment-level triggers 217 directory-based 223, 353 disabling 233 file-based 222, 351 macrodeploy triggers 217 microdeploy triggers 218 package files 233 requirements 215 reverse deployments 224 scripting 227 scripts, allowed 229 scripts, ordering 230 secure invocation 234 task-level triggers 218 TeamSite comparison 115 triggers 216 OpenDeploy Administration Guide

Windows desktop, interacting 216 deploy element 440 deployment authorization checking 68 instances 69 deployment attribute 151 Deployment Configuration Composer 49, 335 accessing 336 comparison rules 375 concurrency management 344 DataDeploy wrapper files 384 definitions 340, 357 Deploy and Run 349 details 338 editing deployments 383 encryption 344 errors tab 337 file naming 342 filters 366, 381 follow links 371 forward deployments 357 global deployment settings 339 group translation 380 log rules 342 new configurations 341 next-tier deployments 348 older configurations 383 parameter namespace 342 permission rules 378 replication farms 347 reverse deployments 357 saving 382 settings 339 source file location 358, 361 source host name 343 target file location 373 target host nodes 347 targets, alternate 372 timeout 344 transactional deployments 349 transmission rules 376 tree tab 337 user translation 380 deployment configurations ACLs 198 comparison rules 187, 375 composing 49 creating 341 definition 100

definitions 93, 340, 357 Deploy and Run 101, 215, 349 editing 383 encoding 82 encryption 344 examples 143 file naming 82, 342 file transport buffer size 196 filters 175, 366, 381 forward deployments 357 group translation 380 host specification 86 log rules 342 logging 67, 142 next-tier 348 overrides 140, 141 parameter namespace 342 permission rules 193, 378 replication farms 347 reverse deployments 357 saving 382 settings 339 source file location 93, 358, 361 source host name 343 source-based overrides 140 structure 83 symbolic links 201 target file location 97, 373 target nodes 347 target replication farms 89, 90 target-based overrides 141 targets, alternate 372 tasks 100 transactional 100, 349 transfer rules 190 transmission rules 376 uploading 52 user translation 380 XML code 50, 79 deployment element 100, 146 deployment groups 53 access controls 56 creating 54 directory permissions 55 viewing 55 deployment information stream format 231 usage 231 deployment reports 301 507

deploymentConfiguration element 83 deploymentDir attribute 466 DeploymentName element 462 deployments asynchronous 70 authorization 74, 75, 76 cancelling 60, 70 compare phase 60, 61 compression 192 data asset 135 directory comparison 102 exclusions 175 extended attributes 114 fan-out 146 file list 116 filtered 175 forward 357 groups 53 instance naming 58 instances 206 legacy Web sites 144 metadata-based 130 monitoring 63 multi-tiered 149 organizing 53 package 233 parameter substitution 70, 203 payload adapter-based 121 pre-commit phase 61 remote upgrade 385 reporting 271 reverse 168, 357 routed 156 running 56, 67 scheduled 235 scheduling 237 simulated 59, 69 starting 56, 57, 68, 242 TeamSite comparison 107, 112 test 59 timeout 87 transactional 145 transfer phase 61 types 79, 145, 335 deployNRun element 101, 219 deployServerConfiguration element 233 description attribute 469 directory attribute 193, 251, 264 directory comparison 102 508

EAs, changes 106 source file location 102 target file location 105 TeamSite areas 103 time zone differences 106 discrete element 417 DLL element 466 DLLs element 466 dnrDeployment element 220 dnrDeploymentJob element 217 dnrDir element 220, 223 dnrFile element 220, 222 documentation, OpenDeploy 13, 15 doDeletes attribute 120, 178, 190 dontDo attribute 190 E EasyDeploy fan-out deployments 147 multi-tiered deployments 152 elements 80 ACDeploy 461 action 129, 449, 455 admin 449 allowedDirectories 28 allowedHosts 28 and 128 application 454 Applications 462 appsvr 454 areaDiff 94, 108 AssemblyNameToUninstall 469 BEABulkLoader 458 cacheProperties 446 clearcase 476 clearcaseCheckout 477 clearcaseItem 478 clearcaseUpdate 477 comparisonRules 187, 188 COMPLUS 462 COMPLUSApplication 466 Component 466 Components 466 Credential 462 custom 125 database 285 databaseDeployment 214 definition 93, 146, 147 delivery 412 OpenDeploy Administration Guide

deploy 440 deployment 100, 146 deploymentConfiguration 83 DeploymentName 462 deployNRun 101, 219 deployServerConfiguration 233 discrete 417 DLL 466 DLLs 466 dnrDeployment 220 dnrDeploymentJob 217 dnrDir 220, 223 dnrFile 220, 222 email 415 emailSet 415 endTime 419 environment 279 eventReporting 272 exceptPath 183 exceptPattern 184 excludePath 181 excludePattern 182 execDeploymentTask 100, 147 external 89, 92 filelist 94, 118 fileSystem 94, 102 filters 177 frequency 417 ftp 414 ftpSet 414 genericAdapter 440 includePath 179, 180 internal 89 iwStore 94, 108 key 127 load 459 localNode 86, 88, 163, 317, 318, 319, 330 log 275 logRules 28, 266 monthly 419 MSAppCenter 461 MSCOM 465 MSGAC 468 name (vss) 480 netCacheServerConfiguration 445 nextDeployment 151 NoACL 462 nodeInfo 163 NodeName 462

nodeRef 90, 147, 178 numericType 127 odAdapter 210 odAdapterSet 210 once 417 opendeploy 413 or 128 path 104, 105, 111 pathSpecification 104, 105, 111, 178 payload 94, 122 payLoadProperties 123 payLoadRules 125 portal 456, 491 predicate 126 Properties 466 Property 466 property 286 pvcs 483 pvcsGet 483 pvcsItem 484 query 125 ReferenceInfo 469 remoteDiff 94, 102 replicationFarm 90, 147, 148 replicationFarmLink 89, 170 replicationFarmSet 90 restrictDnr 233 reverseSource 170 reverseTarget 170 rollback 440 routedDeployment 166 routeDefinition 162 schedule 416 script 227 serverSet 445 Source 462 source 93, 105, 106 sourceFilesystem 97 sourceTeamsite 97 sourceTransferRules 201 startTime 416 subscription 411 target 93, 97, 106 targetFilesystem 112 targetRules 140, 178 Targets 462 targetTeamsite 112, 113 taskoptions 455 textType 127 509

transferRules 190, 192 transportProperties 196 userName (Credential) 462 vss 480 vssCheckout 480 vssGet 480 vssItem 481 websphere 491 weekly 418 wsadmin 454 wscfg 454, 456 xmlaccess 456, 491 email adapters 442 adapter configuration 443 configuration file 443 deployment configuration 443 email element 415 emailSet element 415 enabled attribute 272 encryption 344 SSL data transfer 319 symmetric key 317 types 317 endTime element 419 environment element 279 eventReporting element 272 example deployment configurations 143 exception filters 182 compatibility 185 file system-based 183, 370 pattern-based 184, 370 exceptPath element 183 exceptPattern element 184 excludePath element 181 excludePattern element 182 exclusion filters 181 compatibility 185 file system-based 181, 368 pattern-based 182, 369 exec (ODMSAppCenterConfig) attribute 461 exec (wsadmin) attribute 454 exec (xmlaccess) attribute 456, 491 execDeploymentTask element 100, 147 execPath (clearcase) attribute 476 execPath (pvcs) attribute 483 execPath (vss) attribute 480 explodedFormat attribute 449 extended attributes 113 manfist file 114 510

external element 89, 92 F fan-out deployments 146 EasyDeploy 147 quorum 148 transactional 147 file attribute 193 file integrity, checking 60 file list directories, auto-generating 118 file specification 118 UNIX 117 Windows 117 file list deployments 116 doDeletes option 120 file list 118 source file location 117 symbolic links 119 target file location 119 file list differential deployments 472 base server configuration 472 deployment configuration 472 file list, editing 473 file manifest determination 161 file editing 117 file transport buffer size 196 filelist element 94, 118 filename attribute 454, 456, 491 fileNewerThan attribute 484 filePath attribute 118 files base server log 254, 267 log 36, 251, 265 macro deployment log 256 micro deployment log 258 receiver log 255 receiver macro deployment log 257 receiver micro deployment log 261 source macro deployment log 256 source micro deployment log 259 fileSystem element 94, 102 fileTimestamp attribute 480, 481 fileUseCurrentTime attribute 484 filters 175, 366 combining types 185 exception 182, 185, 370 exclusion 181, 185, 368, 369 OpenDeploy Administration Guide

inclusion 179, 185, 367, 368 override precedence 178 path syntax 185 source-side 177 source-target interaction 178 target-side 177, 381 filters element 177 follow links 201 source-side 371 target-side 371 followLinks attribute 201 force attribute 469 format attribute 127 frequency element 417 From (email adapter) attribute 443 from attribute 195 fromNode attribute 163 FTP adapters 441 adapter configuration 441 configuration file 441 deployment configuration 442 passive mode 441 ftp element 414 ftpSet element 414 G gacutilPath attribute 468 generic delivery adapters 439 adapter configuration 440 deployment configuration 440 genericAdapter element 440 group attribute 193 group ownership transferal 195 group translation 380 H Host (email adapter) attribute 443 Host (FTP adapter) attribute 403, 441 host (ftp) attribute 414 host (localNode) attribute 86 host (odNode) attribute 294 host (server) attribute 445 host (wsadmin) attribute 454 host (xmlaccess) attribute 456, 491 host reporting configuration file 273 location 275 logging 275 hostName attribute 277 hostRmiPort attribute 277

hour (endTime) attribute attributes hour (endTime) 419 hour (startTime) attribute 416 hourly attribute 418 I IBM Rational ClearCase adapter 475 checkout command 475 configuration 475 update command 475 IBM WebSphere adapters 453 IBM WebSphere Portal adapter 490 configuration 490 ID attribute 466 id attribute 469 ignoreAcls attribute 188, 199 ignoreGroup attribute 188 ignoreModes attribute 188 ignoreUser attribute 188 includePath element 179, 180 inclusion filters 179 compatibility 185 file system-based 179, 367 pattern-based 180, 368 instanceName (schedule) attribute 416 instances naming 58 parameter substitution 206 specifying 69 Intelligent Delivery module 389 internal element 89 invokeOnSuccess attribute 151 isEventDLL attribute 466 isPasswordEncrypted attribute 445 itemPath (clearcaseItem) attribute 478 itemPath (pvcsItem) attribute 484 itemPath (vssItem) attribute 481 iwodauthorize 76 iwodcmd offeradd 409 offerdelete 423 offerget 422 subscriptionadd 420 subscriptiondelete 423 subscriptionget 422 iwodcmd archive 437 iwodcmd schedactivate 249 iwodcmd schedadd 242, 244 511

iwodcmd scheddelete 247 iwodcmd schedget 245 iwodcmd serverreset 28, 29 iwodcmd serverstatus 48 iwodcmd start 67, 68 iwodcmd subscriptionschedupdate 425 iwodcmd subscriptionsuspend 423 iwodnetcache 446 iwodnonroot 24 restrictions 27 iwodservergetversion 47 iwodstart status codes 68 iwStore element 94, 108 K key (request) attribute 388 key element 127 keyFile attribute 317, 318 L label attribute 480, 481 legacy Web sites, deploying 144 level attribute 264 load element 459 loaderClassPath attribute 459 localNode element 86, 88, 163, 317, 318, 319, 330 localPath attribute 480, 483 location (dnrDeployment) attribute 220 location (dnrDeploymentJob) attribute 217 location (dnrDir) attribute 223 location (dnrFile) attribute 222 lock attribute 483 lockTimeout attribute 446 log attribute 478 log element 275 log files archived 266 base server 36 location 251 macro deployment 256 manifest 213 micro deployment 258 monitoring 35 permissions 251 receiver 36 receiver macro deployment 257 receiver micro deployment 261 recovery 267 512

size 265 source macro deployment 256 source micro deployment 259 viewing 252 logFile attribute 445 logging 251 adapters 269 administration server 268 base server 254, 264 command line 262 deployment configurations 142 file location 251 file permissions 251 file size 265 hierarchy 264 host file recovery 267 levels 262, 343 macro deployment 67, 256, 265 micro deployment 258, 265 receiver 255, 264 receiver macro deployment 257 receiver micro deployment 261 recovery 267 reporting 275 reporting server 277 rollover naming 266 rollover threshold 265, 342 rules 342 source macro deployment 256 source micro deployment 259 SSL encryption 333 user interface 262 logging levels normal 57, 262, 264, 343 verbose 57, 262, 264, 265, 343 login 30 first time 32 normal 30 logLevel attribute 124, 210 logRules element 28, 266 M macro deployment logs 67, 256 recovery 267 manifest log 213 mask (dnrDir) attribute 223 mask (dnrFile) attribute 222 maxAge attribute 446 maxBytes attribute 263, 266 OpenDeploy Administration Guide

metadata-based deployments 130 arbitrary repositories 133 other adapters 133 TeamSite repositories 131 micro deployment logs 258 recovery 267 Microsoft application center adapters 460 adapter configuration 460 deployment configuration 463 Microsoft COM+ delivery adapters 464 adapter configuration 464 deployment configuration 467 Microsoft GAC provisioning adapters adapter configuration 468 deployment configuration 469 Microsoft global assembly cache provisioning adapter 468 Microsoft Visual SourceSafe adapter 478 checkout command 478 configuration 478 get command 478 minAge attribute 446 minute (endTime) attribute 420 minute (startTime) attribute 416 MKS Source Integrity adapter 487 configuration 487 monitoring 63 completed deployments 66, 67 source deployments 66 target deployments 66 viewing options 64 month (endTime) attribute 419 month (startTime) attribute 416 monthDays attribute 419 monthly element 419 MSAppCenter element 461 MSCOM element 465 MSGAC element 468 multi-tiered deployments 149 EasyDeploy 152 nextDeployment element 151 quorum 153 restrictions 153 multiTierTransactional attribute 151, 152 N name (action) attribute 129, 449, 455 name (clearcase) attribute 476 Name (COMPLUSApplication) attribute 466

name (database) attribute 285 name (DLL) attribute 466 name (email) attribute 415 name (environment) attribute 279 name (external) attribute 89, 92 name (ftp) attribute 414 name (internal) attribute 89 name (key) attribute 127 name (localNode) attribute 163 name (log) attribute 275 name (odAdapter) attribute 210 name (path) attribute 104 name (payLoadProperties) attribute 124 name (process) attribute 278 name (Property) attribute 466 name (property) attribute 286 name (pvcs) attribute 483 name (replicationFarm) attribute 90 name (routeDefinition) attribute 162 name (transportProperties) attribute 196 name (vss) element 480 NetCache adapters adapter configuration 445 deployment configuration 446 internationalization 447 netCacheServerConfiguration element 445 Network Appliance NetCache adapters 444 nextDeployment element 151 next-tier deployments 348 NoACL element 462 noData attribute 477 node attribute 454 nodeInfo element 163 NodeName element 462 nodeRef element 90, 147, 178 nodes configuration file 38 target replication farms 92 nologo attribute 469 non-Administrator, running OpenDeploy as 24 non-root permissions, changing 25 running OpenDeploy as 24 start up script 26 normal logging level 57, 262, 264, 343 nostage attribute 450 notation conventions 14 noWarn attribute 477 numericType element 127

513

O obscured (environment) attribute 279 obscured (property) attribute 286 odAdapter element 210 odAdapterSet element 210 offers 390, 408 customer defined rules 362, 396 deleting 399, 423 deployment groups 395 displaying 422 editing 399 payload deployment actions 365, 398 payload deployments 362, 395 processing 409 query syntax 363, 396 omask attribute 193 once element 417 online help 15 OpenDeploy ACLs 198 Archival module 431 attributes 79, 81 comparison rules 187 configuration DTDs 79 daemons 19 DataDeploy module 214 delivery adapters 439 Deploy and Run 215 deployment types 79, 145, 335 documentation 13, 15 elements 79, 80 encryption 317 file integrity 60 Intelligent Delivery module 389 logging 251 login 30, 32 login options 30 monitoring 63 non-Administrator, running as 24 non-root, running as 24 online help 15 permission rules 193 reconnecting to a restarted server 47 refreshing 28 reporting 271 roles 71 schedules 235 servers 33 services 18, 19, 21, 22 514

starting 17, 19 status 48 stopping 21, 23 syndication 389 transfer rules 190 user interface 17, 20, 29, 30 version 47 Web services 427 Web site integrity 60 OpenDeploy Administration Guide notation conventions 14 usage 13 opendeploy element 413 OpenDeploy Installation Guide 15 OpenDeploy Reference 15 OpenDeploy Release Notes 15, 29 operator attribute 126 or element 128 output attribute 480, 481, 483 outputfile attribute 491 override attribute 484 overrides source-based 140 target-based 141 overwrite attribute 477 P package files 233 parameter (email) attribute 415 parameter (ftp) attribute 414 parameter (odAdapter) attribute 210 parameter (payLoadProperties) attribute 124 parameter substitution 203 adapters 206 command-line 205 default values 204 deployments 70 namespace 342 namespaces 207 scheduled deployments 206, 244 user interface 204 parameterNS (custom) attribute 125 parameterNS (deploymentConfiguration) attribute 83 parameterNS (odAdapter) attribute 210 parameters (schedule) attribute 416 password (admin) attribute 449 password (Credential) attribute 462 Password (FTP adapter) attribute 403, 441 OpenDeploy Administration Guide

password (ftp) attribute 414 password (load) attribute 459 password (pvcsGet) attributes 483 password (server) attribute 445 password (vssCheckout) attribute 480 password (vssGet) attribute 480 password (wsadmin) attribute 454 password (xmlaccess) attribute 456, 491 passwordEncoded (load) attribute 459 passwordEncoded (vssCheckout) attribute 480 passwordEncoded (vssGet) attribute 481 passwordEncoded (wsadmin) attribute 454 passwordEncoded (xmlaccess) attribute 456, 491 passwordEncoded attribute 449, 461, 483 path attribute 275 path element 104, 105, 111 pathSpecification element 104, 105, 111, 178 payload adapter-based deployments 121 payload adapters 471 CVS 485 database 474 deployment actions 129 file list differential 472 IBM Rational ClearCase 475 IBM WebSphere Portal 490 input, providing 125 JDK requirements 471 logging 269 metadata-based deployments 130 Microsoft Visual SourceSafe 478 MKS Source Integrity 487 PCDATA string 125 query syntax 126 sample 471 Serena PVCS 482 software configuration management 475 source file location 122 specifying 123 target file location 123 writing 129 payload element 94, 122 payLoadProperties element 123 payLoadRules element 125 permission rules 193, 378 cross-platform 195 ownership transferal 195 permissions, file 193 Port (FTP adapter) attribute 441 port (odNode) attribute 294

port (server) attribute 445 port (wsadmin) attribute 454 port (xmlaccess) attribute 456, 491 portal element 456, 491 predicate element 126 preserveAcls attribute 190, 194, 199 preserveTime attribute 477 preservetime attribute 477 previousArea attribute 60, 107, 108, 109, 110, 111 projectDB attribute 483 projectPath attribute 483 promotionGroup attribute 484 Properties element 466 Property element 466 property element 286 proxyStubDLL attribute 466 publisher attribute 277 pvcs element 483 pvcsGet element 483 pvcsItem element 484 pwd (wsadmin) attribute 454 Q query element 125 query-based deployments linked queries 128 quick reports 313 list 313, 314 SQL query reports 313 quorum fan-out deployments 148 multi-tiered deployments 153 quorum attribute 148 R receiver logging 255 reporting 272 starting 20 receiver configuration file 38 reporting 272 receiver log file 36, 255 recovery 267 receiver macro deployment log file 257 receiver micro deployment log file 261 recordExtAttr attribute 114 recursive attribute 480, 481, 483 ReferenceInfo element 469 regex (exceptPattern) attribute 184 515

regex (excludePattern) attribute 182 regex (includePattern) attribute 180 regular expressions supported 186 use of "^" character 187 remote upgrades deployments 385 progress checking 387 remote action requests 386 request action 388 remoteDiff element 94, 102 rename attribute 477 replication farms 347 replicationFarm element 90, 147, 148 replicationFarmLink element 89, 170 replicationFarmSet element 90 reporting 271 administration server 276 base server 272 ControlHub custom reports 307 custom reports 297 DAS custom reports 305 database sizing 316 deleting 315 enabling 272 host configuration 272 host reporting configuration file 272 logging 275 maintenance 315 quick reports 313 receiver 272 servers, adding 294 SQL reports 310 store-and-forward system 295 tables, upgrades 291 reporting management configuration file 276 reporting server configuration file, location 276 connection management 277 environment variables 279 logging 277 sub-process commands 278 reporting server database 280 configuration 285 Hypersonic, resetting 287, 288 Hypersonic, upgrading 289 name 286 password 286 resetting 286 516

upgrading 292 using own 280 reportsing deployment 301 repository attribute 459 repositoryType attribute 459 reserved attribute 477 restartMarker (odReportingConfiguration) attribute 277 restrictDnr element 233 reverse deployments 168 configuration 170 Deploy and Run 224 multiple definitions 170 server configuration 169 symmetric key encryption 318 target replication farms 92 reverseSource element 170 reverseTarget element 170 revert attribute 188 revision attribute 484 rmReadOnly attribute 191 roles 71 Administrator 71, 73 server 73 User 72, 73, 74, 75 workflows 78 rollback element 440 rollover threshold 342 logging 265 naming 266 size 266 roundRobbin (odReportingConfiguration) attribute 277 route definitions 156, 162, 166 route segments 156 routed deployments 156, 159, 161 configuration 162, 163 configuring 356 host checking 167 limitations 167 manifest information stream 162 route definitions 156 transactional 356 routedDeployment element 166 routeDefinition element 162 routeSegments 163 rules comparison 187 OpenDeploy Administration Guide

permission 193 transfer 190 S schedule configuration file 425 schedule element 416 scheduled deployments 235 activating 241, 248 command line 242 comments, use of 244 creating 237 deactivating 241, 248 deleting 241, 247 editing 240 end-date 244 one-time 243 parameter substitution 244 recurring 244 time zones 236 user interface 236 viewing 239, 245 schedules (syndication) 406, 425 changing 407 end time 419 frequency 417 start time 416 scheme attribute 469 script element 227 scripting, Deploy and Run 227 Serena PVCS adapter 482 configuration 482 get command 482, 485, 487 server configuration files uploading 36 viewing 38 server element 445 server groups 40 configuration files, editing for 43 creating 40 refreshing 46 updating files 44 viewing 42 server roles 73 access 73 serverClusterFlag attribute 454 serverPath attribute 480 servers adding 33 changing 34

deleting 35 groups 40 log files 36 managing 33 monitoring 35 refreshing 38 serverSet element 445 services resetting 28 starting 18, 19 stopping 21, 22 setAccess attribute 190, 194 silent attribute 469 simulated deployments 59, 69 software configuration management adapters 475 CVS 485 IBM Rational ClearCase 475 Microsoft Visual SourceSafe 478 MKS Source Integrity 487 Serena PVCS 482 Source element 462 source element 93, 105, 106 source file location 93, 358, 361 directory comparison 102 file list deployments 117 legacy configuration syntax 97 modifying files during deployment 97 TeamSite comparison 108 TeamSite on UNIX 120 Windows path naming 99 source hosts area 104, 111 overrides 140 source macro deployment log file 256 source micro deployment log file 259 sourceAccessibility attribute 449 source-based overrides 140 sourceFilesystem element 97 sourceTeamsite element 97 sourceTransferRules element 201 SQL reports 310 downloading 312 generating 312 queries 311, 312 quick reports, saving as 313 SSL data transfer encryption 319 certificate authority 320, 321 certificate generation 323 certificate verification 327 517

ciphers 330 configuration 329 logging 333 OpenSSL defaults, changing 326 setting up 319 SSL errors 326 testing 332 sslCaCertificate attribute 329 sslCertificate attribute 329 sslCiphers attribute 330 sslPrivateKey attribute 329 sslVerifyPeer attribute 329 stage attribute 450 standalone database deployments 136 startAppFlag attribute 455 startCommand attribute 278 startDir attribute 279 startTime element 416 state (dnrDeployment) attribute 220 state (dnrDeploymentJob) attribute 217 state (dnrDir) attribute 223 state (dnrFile) attribute 222 stderr attribute 279 stdin attribute 279 stopCommand attribute 278 stout attribute 279 sub-hourly attribute 418 Subject (email adapter) attribute 443 subPath (exceptPath) attribute 183 subPath (excludePath) attribute 181 subPath (includePath) attribute 179 subscription element 411 subscriptions 390, 400, 410 activating 424 deleting 406, 423 delivery methods 402, 412 deployment groups 406 displaying 422 processing 420 schedules 406 suspending 407, 423 updating 425 viewing from offer 407 svrOrClusterName attribute 454 svrTryCount attribute 191 svrTryDisableOverwrite attribute 191 svrTryInterval attribute 191 symbolic links target file location 98 518

symmetric key encryption 317 configuration 317 reverse deployments 318 synchronized deployments 138 syndication 389 activating 424 command-line 408 deleting files 423 delivery methods 412 displaying files 422 email 415 FTP 414 offers 390, 391, 408 OpenDeploy 413 schedules 391, 406, 425 subscription updating 425 subscriptions 390, 400, 410 suspension 423 user interface 391 Web services 426 T target element 93, 97, 106 target file location 97, 373 alternate 140 directory comparison 105 file list deployments 119 mixed platforms 98 multiple source deployments 98 symbolic link 98 TeamSite comparison 112 Windows path naming 99 target hosts alternate 140 area 141 features, defining 142 overrides 141 root directories 106 target replication farms 89 backwards compatibility 90 deployment configuration 90 location 89 multiple references to same host 91 nodes configuration file 92 reverse deployments 92 target-based overrides 141 TargetDir (FTP adapter) attribute 403, 441 targetDir (ftp) attribute 414 targetFilesystem element 112 OpenDeploy Administration Guide

targetFollowLinks attribute 119 targetRules element 140, 178 targets attribute 449 Targets element 462 target-side database deployments 137 targetTeamsite element 112, 113 taskoptions element 455 TeamSite extended attributes, deploying 113 TeamSite comparison 107 Deploy and Run scripts 115 extended attributes, deploying 113 legacy Web sites 144 previousArea 109 source file location 108 target file location 112 using //IWSERVER 110 test deployments 59 textType element 127 time zones directory comparions 106 scheduled deployments 236 timeout host inactivity 87, 344 user interface 32 timeout attribute 87 tmpDir (emailSet) attribute 415 tmpDir (ftpSet) attribute 414 To (email adapter) attribute 443 to attribute 195 toNode attribute 163 transactional routed deployments 356 transactional (opendeploy) attribute 413 transactional (routedDeployment) attribute 166 transactional attribute 100, 147 transactional deployments 100, 145, 349 fan-out 147 multi-tiered 152 routed deployments 161 transfer rules 190 transferRules element 190, 192 transmission rules 376 transportProperties element 196 triggerPoint attribute 220 type attribute 127, 466 typeLibrary attribute 466

U unspecified routes, resolving 159 unsubscribed attribute 294 useDefinition attribute 147 useName (wsadmin) attribute 454 useNode attribute 90, 147 User (FTP adapter) attribute 403, 441 user (ftp) attribute 414 user (permissionRules) attribute 193 user interface 29 browser requirements 29 login 30 scheduled deployments 236 servers 33 starting 20, 30 timeout setting 32 user ownership transferal 195 User role 72, 73, 75 access 74 user translation 380 userconfigfile attribute 449 userId attribute 483 userid attribute 445 userkeyfile attribute 449 userName (Credential) element 462 userName (load) attribute 459 userName (vssCheckout) attribute 480 userName (vssGet) attribute 480 userName (xmlaccess attribute 456 userName (xmlaccess) attribute 491 userName attribute 449 useRouteClass attribute 166 useRouteDefinition attribute 166 useServerNodeHost attribute 166, 167, 356 V value (environment) attribute 279 value (predicate) attribute 127 value (Property) attribute 466 value (property) attribute 286 verbose logging level 57, 262, 264, 265, 343 version (clearcaseCheckout) attribute 477 version (MSCOM) attribute 465 version (MSGAC) attribute 468 version (ODMSAppCenterConfig) attribute 461 version (odNode) attribute 294 version (pvcsGet) attribute 484 version (vssCheckout) attribute 480 version (vssGet) attribute 481 519

vss element 480 vssCheckout element 480 vssGet element 480 vssItem element 481 W Web services 427 syndication 426 Web site integrity, checking 60 WebLogic 8 adapters adapter configuration 448 deployment configuration 450 upload directory 450 WebLogic 9 adapters adapter configuration 451 deployment configuration 451 weblogicJar attribute 449 webServerName attribute 445 WebSphere adapters adapter configuration 453 application server 454, 457 deployment configuration 457 portal server 456, 457 websphere element 491 weekday attribute 418 weekly element 418 when (dnrDeployment) attribute 220 when (dnrDeploymentJob) attribute 217 when (dnrDir) attribute 223 when (dnrFile) attribute 222 where attribute 227 Windows desktop, Deploy and Run 216 workSpace attribute 483 writable attribute 481, 484 writableFiles (vssCheckout) attribute 480 writableFiles attribute 481 wsadmin element 454 wscfg element 454, 456 X XML code 50 xmlaccess element 456, 491 Y year (endTime) attribute 419 year (startTime) attribute 416

520

OpenDeploy Administration Guide