Open Deploy Admin Guide 7.2

OpenDeploy®Administration Guide

Version 7.218 August 2010

Notice

This documentation is a proprietary product of Autonomy and is protected by copyright laws and international treaty. Information in this documentation is subject to change without notice and does not represent a commitment on the part of Autonomy. While reasonable efforts have been made to ensure the accuracy of the information contained herein, Autonomy assumes no liability for errors or omissions. No liability is assumed for direct, incidental, or consequential damages resulting from the use of the information contained in this documentation.

The copyrighted software that accompanies this documentation is licensed to the End User for use only in strict accordance with the End User License Agreement, which the Licensee should read carefully before commencing use of the software. No part of this publication may be reproduced, transmitted, stored in a retrieval system, nor translated into any human or computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual or otherwise, without the prior written permission of the copyright owner.

This documentation may use fictitious names for purposes of demonstration; references to actual persons, companies, or organizations are strictly coincidental.

Trademarks and Copyrights

Copyright © 2010 Autonomy Corporation plc and its affiliates. All rights reserved. Advise, AudioLogger, Autonomy etalk, ContentServices, ControlHub, DataDeploy, etalk PRO, etalk, e-talk, Expert, Explore, Interwoven, LiveSite, MediaBin, MetaTagger, Observe, OpenDeploy, Optimost, Qfiniti Enterprise 3, Qfiniti, Recorder, SoftSound , SoftSound Analysis Plug-in, Survey, TeamSite, Virage ControlCenter, Virage Encoder, Virage SmartEncode, Virage VideoLogger, Virage, VisualAnnotate, VS Archive, VS Broadcast Monitoring, and all related titles and logos are trademarks of Autonomy Corporation plc and its affiliates.

Microsoft is a registered trademark, and MS-DOS, Windows, Windows 95, Windows NT, SharePoint, and other Microsoft products referenced herein are trademarks of Microsoft Corporation.

UNIX is a registered trademark of The Open Group.

AvantGo is a trademark of AvantGo, Inc.

Epicentric Foundation Server is a trademark of Epicentric, Inc.

Documentum and eRoom are trademarks of Documentum, a division of EMC Corp.

FileNet is a trademark of FileNet Corporation.

Lotus Notes is a trademark of Lotus Development Corporation.

mySAP Enterprise Portal is a trademark of SAP AG.

Oracle is a trademark of Oracle Corporation.

Adobe is a trademark of Adobe Systems Incorporated.

Novell is a trademark of Novell, Inc.

Stellent is a trademark of Stellent, Inc.

All other trademarks are the property of their respective owners.

Notice to Government End Users

If this product is acquired under the terms of a DoD contract: Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of 252.227-7013. Civilian agency contract: Use, reproduction or disclosure is subject to 52.227-19 (a) through (d) and restrictions set forth in the accompanying end user agreement. Unpublished-rights reserved under the copyright laws of the United States. Autonomy, Inc., One Market Plaza, Spear Tower, Suite 1900, San Francisco, CA. 94105, US.

8/18/10

Copyright Notice

•

Contents

Figures 13

Tables 15

Procedures 17

About this Book 21Intended Audience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Notation Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Chapter 1: Introduction to OpenDeploy 25The OpenDeploy Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Base Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Receiver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Administration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Reporting Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27ContentServices Foundation Access Service . . . . . . . . . . . . . . . . . . . . . . . . . . . 27TeamSite. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

How OpenDeploy Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Source-Target Relationship . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Deployment Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30File Location Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31File Deployment Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Graphical User Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Deployment Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Directory Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35File List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35TeamSite Comparison. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Payload Adapter-based Deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Query-based Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Content Delivery Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Deployment to a Single Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Deployment to Multiple Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Multitiered Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Routed Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Transactional Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

OpenDeploy® Administration Guide 3• • •••

Contents

4

Specify a Target Quorum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Reverse Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Access Rights and Privileges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Administrator Role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43User Role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Chapter 2: Get Started 45Start OpenDeploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Start the User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Stop OpenDeploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Run Multiple Instances of OpenDeploy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Services and Daemons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Instance Names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Properties File Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Define OpenDeploy Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Start and Stop an Instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Configure Instances as Target Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Use Database Auto-Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Run OpenDeploy as Non-Administrator or Non-Root. . . . . . . . . . . . . . . . . . . . . . . 61Run OpenDeploy on Windows as Non-Administrator . . . . . . . . . . . . . . . . . . . . 61Run OpenDeploy on UNIX as Non-Root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Refresh the OpenDeploy Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66OpenDeploy User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Browser Refresh Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Access the User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Log In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Timeout Setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

OpenDeploy Server Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Add an OpenDeploy Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Change Server Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Delete OpenDeploy Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Monitor Server Logs and Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Server Management Window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77View the Base Server and Receiver Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . 78Upload Modified Server Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . 78View Server Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Refresh the OpenDeploy Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Server Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Create a Server Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

OpenDeploy® Administration Guide

• • • •••

Contents

•

View Server Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Server Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Edit a Server Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Delete a Server Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Manage Server Group Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Refresh the Server Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Reconnect to a Restarted OpenDeploy Server . . . . . . . . . . . . . . . . . . . . . . . . . . 90Determine the OpenDeploy Server Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Display the OpenDeploy Server Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Compose Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Use a Text or XML Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Use the Deployment Configuration Composer . . . . . . . . . . . . . . . . . . . . . . . . . . 92

View Deployment Configuration Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92Upload Deployment Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Upload Configuration Dialog Box. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Organize Deployment Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Create Deployment Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96View Deployment Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Directory Permissions for Deployment Groups . . . . . . . . . . . . . . . . . . . . . . . . . 98Assign Access Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Run a Deployment from the User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Deployment Started Window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Deployment Instance Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Perform a Test Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Perform a Simulated Deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Check File Integrity on Production Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Cancel Deployments in Progress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Monitor Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Source Deployments Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

View Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Deployments Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Details Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Source Deployments Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Completed Sent Deployments Limit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Target Deployments Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111Details Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Completed Received Deployments Limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Deployment Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Run Deployments from the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Authorization Checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Start a Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Perform a Simulated Deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Specify a Deployment Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Run Deployments Asynchronously . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116Cancel a Deployment in Progress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116


Contents

6

Roles and Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Administrator Role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117User Role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Server Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

Server Access Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119Assign or Revoke Server Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Deployment and Deployment Groups Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Deployment Authorization Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Authorize Deployments and Deployment Groups from the Command-Line . . 123Role Access in TeamSite Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Chapter 3: Server and Host Configuration 129Access Service Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Access Service Management with CSF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129Access Service Management with TeamSite . . . . . . . . . . . . . . . . . . . . . . . . . . 130Web Services Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Modify the Service Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Specify the TeamSite Release. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Specify the Base Server and Receiver Configuration Files . . . . . . . . . . . . . . . 132Specify the Nodes Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Specify the Bootstrap Administrator User Name . . . . . . . . . . . . . . . . . . . . . . . 132Disable the Default Bootstrap Administrator Users . . . . . . . . . . . . . . . . . . . . . 133Specify the Access Service Key File Usage and Name . . . . . . . . . . . . . . . . . . 133Disable Authorization Check for Deployments Invoked with iwodcmd start . . 134Configure RMI Ports for Administration through a Firewall . . . . . . . . . . . . . . 134Update Port Entries from a Previous Release . . . . . . . . . . . . . . . . . . . . . . . . . . 135Specify the RMI Server Host Name or Binding IP Address . . . . . . . . . . . . . . . 136Update Service Configuration File from a Previous Release . . . . . . . . . . . . . . 136

Configure the Bootstrap Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136Default Bootstrap Administrator Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Disable the Default Bootstrap Administrator Users . . . . . . . . . . . . . . . . . . . . . 137Modify the Bootstrap Administrator User . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Configure the Administration Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139Configure a Non-Default RMI Registry Port . . . . . . . . . . . . . . . . . . . . . . . . . . 139RMI Ports for Legacy OpenDeploy Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . 139ContentServices Foundation Access Service . . . . . . . . . . . . . . . . . . . . . . . . . . 140Configure HTTPS for the CSF Access Service . . . . . . . . . . . . . . . . . . . . . . . . 140Configure HTTPS Browser Access for OpenDeploy . . . . . . . . . . . . . . . . . . . . 141Change the Keystore Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Specify an Alternate TeamSite Mount Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144Enable Cross-Platform Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145Define Target Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146Physical Host Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146Logical Server Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147Specify Server Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147


• • • •••

Contents

•

Define Target Replication Farms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149Set up OpenDeploy in a Microsoft Cluster Environment . . . . . . . . . . . . . . . . . . . 151

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151OpenDeploy Server Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152Configure OpenDeploy Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Configure Event Reporting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Microsoft Cluster Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154Deploy into a Microsoft Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156Deploy Content from a Microsoft Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156Administration Package Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Access the OpenDeploy Administration Server in a Microsoft Cluster . . . . . . 158CSF Access Service Package Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Configure the iwodcmd Command-Line Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159Service Configuration File Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159Specify Alternate Ports and Hosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160Migration Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

Deploy through a Firewall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Configuration Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Host Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

Back up OpenDeploy Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162Base Server and Receiver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163Administration/Report Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164Recovery Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165Service Configuration File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165Encoding for XML-based Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . 165Configure File Descriptor Limits on Solaris. . . . . . . . . . . . . . . . . . . . . . . . . . . 166

SNMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Start and Stop SNMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167Configure SNMP for OpenDeploy Instances . . . . . . . . . . . . . . . . . . . . . . . . . . 167Enable and Disable SNMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167SNMP Agent Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168SNMP Agent Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168Set up SNMP Polling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170Disable Alert Notifications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171Object IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172Management Information Base Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Configure DAS for TeamSite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Chapter 4: Server Configuration Files 175Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176Identify the Host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176


Contents

8

Specify the Communication Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177Host Checks during Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177Specify Alternate Locations for Temporary Deployment Files . . . . . . . . . . . . . . . 178Enable Concurrency Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179Clear the Registry of Target Path Entries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181Allow Traversal of Target Links in File List Deployments . . . . . . . . . . . . . . . . . . 181Set the File Transport Buffer Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182Restrict Access to Users with OpenDeploy Roles . . . . . . . . . . . . . . . . . . . . . . . . . 182

Invoke from a TeamSite Workflow External Task . . . . . . . . . . . . . . . . . . . . . . 183Enable Authentication when iwodcmd Commands Run. . . . . . . . . . . . . . . . . . 183Use Strict Authorization in ControlHub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

Set the Number of Connection Retries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184Enable Target-Side Deploy and Run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185Specify the Deployment Information Stream Format . . . . . . . . . . . . . . . . . . . . . . 185Define the Scheduler Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

URL Choices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187Use Third-Party JDBC Drivers with the OpenDeploy Scheduler . . . . . . . . . . . 189

Limit the Size of the Scheduler Script File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190Specify Allowed Hosts for Received Deployments . . . . . . . . . . . . . . . . . . . . . . . . 190

Check for Allowed Hosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191Manage IP Address Checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191Reverse Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192Host Checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

Specify Allowed Directories for Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . 192Logs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

logRules Element Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194Default Log Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196Deployment Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

Specify the Completed Deployments List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197Completed Deployments Sent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198Completed Deployment Received . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Validate Deployment Configuration Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199Serialize Transactional Deployments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

Time-based Serialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200Serialize Randomly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Specify Allowed Deploy and Run Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201Specify Payload Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

HTTP Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203HTTPS Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204Configure both HTTP and HTTPS on Hosts with Multiple IP Addresses . . . . 204


• • • •••

Contents

•

Transport Connection Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205Configure for HTTPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206Manage the Keystore File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

Database Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209Performance Throttle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211Hot Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Chapter 5: Scheduled Deployments 215Schedule from the User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

New Schedule Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216Resolve Time Zone Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218Scheduled Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218View Schedules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221View Scheduled Deployment Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221Edit Scheduled Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222Delete Scheduled Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222Activate and Deactivate Scheduled Deployments . . . . . . . . . . . . . . . . . . . . . . 223

Schedule from the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224Add a Schedule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224View Scheduled Deployment Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227Delete a Schedule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229Activate and Deactivate a Schedule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

Reactivate Schedules During or Past Their Effective Periods . . . . . . . . . . . . . . . . 231

Chapter 6: Logs 233Log File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233Log File Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233View Log Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

View Log Files from a Text Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234View Log Files from the OpenDeploy User Interface . . . . . . . . . . . . . . . . . . . 234

OpenDeploy Log Viewer Window Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235Base Server Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237Receiver Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238Macro Deployment Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

Source Macro Deployment Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240Receiver Macro Deployment Log. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

Micro Deployment Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242Source Micro Deployment Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243Receiver Micro Deployment Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

Log Levels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245Define Log Levels in the User Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246Define Log Levels from the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . 246

Configure Log Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246OD, Base Server, and Receiver Configurations . . . . . . . . . . . . . . . . . . . . . . . . 247Deployment Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

Log Rules Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250


Contents

10

Log File Size Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250Rollover Threshold Size Determination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251Rolled Over Log File Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251Maximum Archives Allowed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

Log File Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252Log File Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253Deployment Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253Administration Server Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253Reporting Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254Adapter Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

Chapter 7: Security 257Sender Node Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

Symmetric Key Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258Secure Data Transfer with SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

Non-root Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275Multi-instance Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275Deploy and Run Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275Command-Line Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275Bootstrap Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275Administration Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276strictAuthentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

allowedEventReportingHost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276Decode Requests to OpenDeploy Server Treated as Decryption . . . . . . . . . . . 276Secure RMI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

Chapter 8: Reports 281Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282

Server Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

Administration Server Configuration for Reports . . . . . . . . . . . . . . . . . . . . . . . . . 284Add Servers to the Report Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284Connection Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285Add OpenDeploy Servers to Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286Subprocess Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287Environmental Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288Report Server Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288Upgrade Report Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294Upgrade the Default Report Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294Use a Third-Party Database for a Store-and-Forward System . . . . . . . . . . . . . 296

Custom Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297Configure Custom Report Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298Generate Custom Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300Download Custom Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304


• • • •••

Contents

•

Save Custom Reports as Quick Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305DAS Custom Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305SQL Query Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

Access to Report Server Database Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308Case Sensitivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308Create SQL Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308Generate SQL Query Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309Download an SQL Query Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309Save an SQL Query Report as a Quick Report . . . . . . . . . . . . . . . . . . . . . . . . . 309

Quick Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310Add New Entries to Quick Report List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311Edit Existing Entries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311Delete Quick Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

Manage Report Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312Report Database Size Guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313Capture Error Messages into an MIB File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

Chapter 9: Troubleshoot Administration Issues 315

Index 319


Contents

12
• • • •••

•

Figures

Figure 1 Single base server and multiple receivers........................................................29Figure 2 Redeploy files using multiple source servers ..................................................30Figure 3 How OpenDeploy uses deployment configurations ........................................31Figure 4 Definitions .......................................................................................................32Figure 5 OpenDeploy user interface ..............................................................................34Figure 6 Deployment to a single target server ...............................................................38Figure 7 Deployment to multiple target servers.............................................................39Figure 8 Multitiered deployment....................................................................................40Figure 9 Transactional deployment................................................................................41Figure 10 Reverse deployment.........................................................................................43Figure 11 OpenDeploy user interface ..............................................................................68Figure 12 OpenDeploy login dialog box..........................................................................70Figure 13 Servers dialog box ...........................................................................................73Figure 14 New Server dialog box ....................................................................................73Figure 15 OpenDeploy Servers dialog box with the new server......................................74Figure 16 Edit Server dialog box .....................................................................................74Figure 17 Server Management window ...........................................................................76Figure 18 Upload a configuration file to a remote OpenDeploy server...........................79Figure 19 View File List and Configuration window ......................................................80Figure 20 OpenDeploy Server Groups dialog box...........................................................82Figure 21 New Server Group dialog box .........................................................................82Figure 22 OpenDeploy Server Groups dialog box...........................................................83Figure 23 Server Groups dialog box ................................................................................83Figure 24 Edit Server Group dialog box ..........................................................................85Figure 25 Server Group Management window ................................................................87Figure 26 Upload a configuration file to a server group ..................................................88Figure 27 Server Group Status pane ................................................................................88Figure 28 View Configuration window ...........................................................................92Figure 29 Deployment Configuration window ................................................................93Figure 30 Upload Configuration dialog box ....................................................................94Figure 31 Append a deployment group to the deployment name ....................................97Figure 32 Deployment Configuration window ................................................................97


Figures

14

•

Figure 33 Deployment Group List when selecting deployment directly under /conf ......98Figure 34 Start a Deployment dialog box .......................................................................99Figure 35 Deployment Started dialog box .....................................................................100Figure 36 Details Table with Cancel Deployment button..............................................104Figure 37 Source Deployments window ........................................................................106Figure 38 Source Deployments dialog box—Details table ............................................109Figure 39 Target Deployments dialog box.....................................................................111Figure 40 Server Access window...................................................................................119Figure 41 Deployment Authorization window..............................................................121Figure 42 Deployment box.............................................................................................122Figure 43 Authorized Deployments box ........................................................................123Figure 44 Allowed hosts and allowed directories ..........................................................193Figure 45 New Schedule window ..................................................................................216Figure 46 New Schedules Frequency features ...............................................................219Figure 47 Schedule end date and time ...........................................................................220Figure 48 Deployment Schedules window....................................................................220Figure 49 Deployment Schedules window showing all scheduled deployments...........221Figure 50 OpenDeploy Log Viewer window.................................................................234Figure 51 Base server log...............................................................................................238Figure 52 Source Macro Deployment log ......................................................................241Figure 53 Source Micro Deployment log.......................................................................244Figure 54 Log Levels in the user interface.....................................................................246Figure 55 Custom Report window .................................................................................298Figure 56 Target Host List when Receiving is selected.................................................299Figure 57 Deployment Report window..........................................................................300Figure 58 Deployment Leg Report.................................................................................302Figure 59 Leg Report Details window ...........................................................................303Figure 60 Deployment Manifest Report.........................................................................303Figure 61 Generated Custom Report open in Microsoft Excel ......................................304Figure 62 DAS Custom Report window ........................................................................305Figure 63 SQL Query Reports window.........................................................................307Figure 64 Generated SQL query report..........................................................................309Figure 65 Deployment Report window.........................................................................310Figure 66 Edit Quick Report window ...........................................................................311Figure 67 Report Maintenance window .........................................................................312

OpenDeploy® Administration Guide• • •••

•

Tables

Table 1 Notation conventions ............................................................................................... 22Table 1 OpenDeploy services............................................................................................... 46Table 2 Services for multiple instances of OpenDeploy ....................................................... 47Table 3 OpenDeploy services............................................................................................... 50Table 4 Services for multiple instances of OpenDeploy ....................................................... 50Table 5 Adapter names used in the log file naming............................................................ 254Table 6 Files for generating the certificate authority ........................................................... 261


Tables

16
• • • •••

•

Procedures

To start the OpenDeploy services .....................................................................................46To start one or more OpenDeploy services from the Windows command line ................47To start the base server or receiver software for UNIX ....................................................48To stop the OpenDeploy services from the Services window ..........................................50To stop one or more OpenDeploy services from the Windows command line ................51To stop the OpenDeploy daemons on a UNIX server ......................................................51To create an instance .........................................................................................................58To remove an instance ......................................................................................................58To disable an instance .......................................................................................................59To enable a disabled instance ...........................................................................................59To disable an instance’s SNMP ........................................................................................59To enable an instance’s disabled SNMP ...........................................................................59To run OpenDeploy on Windows as non-Administrator ..................................................61To convert an OpenDeploy base server or receiver on UNIX to run as non-root ............61To prepare OpenDeploy on UNIX to run as non-root ......................................................62To automatically start OpenDeploy as a non-root user on a Solaris host .........................63To refresh your OpenDeploy server’s configurations ......................................................67To log in to OpenDeploy ..................................................................................................70To change the timeout value of the OpenDeploy user interface .......................................72To add an OpenDeploy server to the user interface ..........................................................73To change the information of a selected OpenDeploy server ...........................................74To delete a selected OpenDeploy server from the user interface .....................................75To view the base server and receiver log files ..................................................................78To upload a modified configuration file to a remote OpenDeploy server ........................79To view the source code of an OpenDeploy server configuration file .............................80To refresh a selected OpenDeploy server’s configuration files ........................................81To create a server group ....................................................................................................82To view the server groups .................................................................................................83To edit a server group .......................................................................................................85To delete a server group ....................................................................................................85To upload modified configuration files to a server group ................................................87To refresh a server group ..................................................................................................89


Procedures

18

•

To view the server group update status ............................................................................89To determine the OpenDeploy server version ..................................................................90To display the status of your OpenDeploy server .............................................................90To view the source code of a deployment configuration ..................................................93To upload a deployment configuration .............................................................................95To view deployment groups and the deployment configurations they contain ................97To start a deployment using the OpenDeploy user interface ..........................................100To perform a simulated deployment ...............................................................................103To cancel a deployment in progress sent by your server ................................................105To monitor the progress of your deployments ................................................................107To start a deployment from the command line ...............................................................114To cancel a deployment in progress from the command line .........................................117To assign or revoke server roles .....................................................................................120To authorize User roles to perform specified deployments on a OpenDeploy server ....122To authorize the set of users to run deployments listed in deployments.txt ...................126To unauthorize this same set of deployments from the same set of users ......................126To reset the user list to include only the deployments in the deployment file ...............126To remove all authorizations without adding new ones .................................................126To have the OpenDeploy server to use the CSSDK key file ..........................................130To modify the bootstrap administrator on a OpenDeploy base server or receiver .........138To configure a non-default RMI registry port ................................................................139To configure admin server to communicate with CSF access service with HTTPS ......140To configure administration server for browser access with HTTPS .............................141To change the keystore password for new installations .................................................142To change the keystore password for existing installations ...........................................143To install each OpenDeploy host in the Microsoft Cluster environment .......................151To set up OpenDeploy server on each node ...................................................................152To configure OD base server or receiver on each node for OD Web service ................153To configure an OD base server and receiver on each node for event reporting ............153To set up Microsoft Cluster setup procedure on each node ............................................154To set up any OpenDeploy base server to deploy content to an OpenDeploy server .....156To configure the CSF access service for the OpenDeploy administration server ..........157To include the Microsoft Cluster in event reporting .......................................................157To configure the CSF access service on each node in the Microsoft Cluster .................158To use the wrapper scripts ..............................................................................................161To recover backed up OpenDeploy component files and directories .............................165To update the daemon.cfg file ........................................................................................173To use third-party JDBC drivers with the OpenDeploy scheduler .................................189To configure your serialization to be time based ............................................................200To configure your serialization to be random .................................................................201To configure OpenDeploy to use HTTPS .......................................................................206To create a new certificate ..............................................................................................207


Procedures

•

To export an existing certificate .....................................................................................208To add an existing certificate ..........................................................................................208To display a list of certificates ........................................................................................209To determine the runmode ..............................................................................................211To configure the hot file feature .....................................................................................213To schedule a deployment ..............................................................................................218To view a deployment schedule ......................................................................................221To edit a scheduled deployment .....................................................................................222To delete a scheduled deployment ..................................................................................222To deactivate a scheduled deployment ...........................................................................223To reactivate a deactivated scheduled deployment .........................................................223To add a schedule to a deployment from the command line ..........................................224To view information on deployment schedules ..............................................................227To view all scheduled deployments on the OpenDeploy server .....................................228To view all schedules for the deployment reports ..........................................................228To view schedule information for the deployment reports with an ID number of “2” ...228To delete a schedule from the command line .................................................................229To activate or deactivate a schedule from the command line .........................................230To deactivate the scheduled deployment reports with an ID of “5” ...............................231To access the base server log from the user interface .....................................................238To access the source macro deployment log from the user interface .............................240To access the source micro deployment log from the user interface ..............................243To set up the OpenSSL certificate authority ...................................................................261To generate a certificate for an OpenDeploy server .......................................................264To use a third-party certificate authority ........................................................................265To test your SSL encryption configuration .....................................................................272To use a third-party certificate authority with SSL encryption ......................................273To enable Secure RMI on the OpenDeploy server .........................................................277To configure client-type passwords on the OpenDeploy server .....................................278To configure additional OpenDeploy instances for secure RMI ....................................279To implement a custom RMI client ................................................................................280To configure your own reporting server database ..........................................................289To reset the reporting database .......................................................................................291To reset the Hypersonic database ...................................................................................292To reset the Hypersonic database when using OpenDeploy with ControlHub ..............292To perform a new installation of the Hypersonic reporting database on Windows ........295To perform a new installation of the Hypersonic reporting database on UNIX .............295To upgrade a legacy Hypersonic reporting database on Windows .................................295To upgrade a legacy Hypersonic reporting database on UNIX ......................................296To configure the store-and-forward database to a commercial database ........................296To create a custom report query .....................................................................................299To download a generated custom ...................................................................................304


Procedures

20

•

To generate DAS custom reports ....................................................................................306To create an SQL query ..................................................................................................308To display the Edit Quick Report window .....................................................................311To delete reports older than a specified time ..................................................................312To capture error messages into the iwopendeploy.mib file ............................................314The RMI-based event report fails with OpenDeploy Admin 6.2.1 and

OpenDeploy-Server 7.0 .............................................................................................315Failure during database migration with the default Hypersonic reporting database ......315Error 12505 occurs while deploying to the clustered database with DataDeploy ..........316Synchronize user locales on Windows ...........................................................................317Cannot share servletd with TeamSite HA .......................................................................317Non-root users cannot run the slibclean command on AIX ............................................317Error during schema creation on Scheduler DB with MySQL .......................................317


About this Book

This guide describes how to configure your OpenDeploy server software and host, and run OpenDeploy deployments.

Intended AudienceThis guide is primarily intended for Webmasters, system administrators, and those involved in deploying content between development servers and production servers.

If you use OpenDeploy with TeamSite®, you should also be familiar with TeamSite functionality and terminology. Many of the operations described in this manual require root or Administrator access to the OpenDeploy server host. If you lack root or Administrator access to the OpenDeploy server host, see your system administrator.

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

This guide uses UNIX to indicate any supported 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 should be familiar with basic commands and be able to use a text editor such as emacs or vi.

It is also helpful to be familiar with regular expression syntax. Refer to a reference manual such as Mastering Regular Expressions by Jeffrey Friedl.

OpenDeploy® Administration Guide 21

• • • •••

About this Book

22

Notation ConventionsThis guide uses the following notation conventions:

Table 1 Notation conventions

Convention Definition and Usage

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

Click Edit File in the Button Bar.

Italic Book titles appear in italics.

Terms are italicized the first time they are introduced.

Important information may be italicized for emphasis.

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

The iwextattr command-line tool allows you to set and look up extended attributes on a file.

Monospaced italic

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

This means that you must replace role and user with your values.

Monospaced bold Monospaced bold represents information you type 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:iwextattr -s project=proj1 //IWSERVER/default/main/dev/WORKAREA/andre/products/index.html

Monospaced bold italic

Monospaced bold italic text is used to indicate a variable in user input. For example:iwextattr -s project=projectname workareavpath

means that you must insert the values of projectname and workareavpath when you type 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.


• • • •••

Notation Conventions

By default, directory paths use UNIX conventions. These conventions mandate using forward slashes (/) in path names. For example:

UNIX: docroot/news/front.html

Windows systems use back slashes (\). The Windows convention is used when referring to a Windows-specific directory. For example:

Windows: docroot\news\front.html


• • • •••

About this Book

24
• • • •••

Chapter 1

Introduction to OpenDeploy

OpenDeploy is an industry-leading content distribution product for deploying static and dynamic enterprise content, including Web sites, code, and documents, to a multitier, multiple server environment. OpenDeploy runs on a variety of common servers, and is well suited for a cross-platform enterprise.

OpenDeploy provides a secure, flexible, and scalable solution for the cross-platform, transactional transfer of content to multiple servers. An open architecture enables OpenDeploy to distribute content managed in any repository or file system. No special tagging of content is required. OpenDeploy empowers users to:

Mobilize IT operations staff with a browser-based user interface for remotely controlling and monitoring distribution activities.

Segment enterprise initiatives and responsibilities with finely grained user rights.

Securely automate content distribution to multiple tiers of servers inside and outside firewalls.

Ensure data integrity and synchronization via transactional distribution to multiple server farms.

Deliver content to the right place at the right time using a built-in scheduler.

Quickly determine results through comprehensive reporting services.

Seamlessly integrate content distribution with business applications and tasks.

Extend content delivery to any device or protocol, thereby implementing a consistent, end-to-end distribution solution.

Expand IT infrastructure without costly custom scripting.

The OpenDeploy software family includes the optional DataDeploy module that enables secure delivery and synchronization of database content. A unified distribution architecture seamlessly combines the advantages of secure, reliable file asset distribution with delivery of structured content to databases that drive Web-based applications.


• • • •••

Chapter 1: Introduction to OpenDeploy

26

The OpenDeploy EnvironmentOpenDeploy consists of a suite of interlocking services that create the OpenDeploy environment. The OpenDeploy environment contains the following components.

Base server software enables the OpenDeploy server to start deployments to other servers, as well as to receive files deployed from other OpenDeploy servers. You can run additional instances of the base server from single base server software installation.

Receiver software enables the OpenDeploy server only to receive deployed files. You can run additional instances of the receiver from a single receiver software installation.

Administration package manages the following OpenDeploy functions:

generation of the browser-based user interface

reporting through the reporting server

access to OpenDeploy servers, features, and functions, based on user and administrator roles

DataDeploy module (optional) adds secure delivery and synchronization of database content.

Archival module (optional) allows the writing of deployed files to storage devices, such as read-once/write-many (WORM) drives.

TeamSite (optional) OpenDeploy includes optimizations for deploying files from selected staging areas, editions, and workareas to file system locations on the target servers.

Base Server

The core of the OpenDeploy environment is the base server. A base server can send and receive deployed files. When the base server deploys files to another server, it assumes the role of the source server in the source/target relationship. If the base server itself is receiving deployed files, its role becomes the target server.

The base server can be a development server within the enterprise firewall or it might be a hub outside the firewall responsible for redeploying files it receives to another set of target servers. The deployment requirements determine the number and positioning of base servers in the OpenDeploy environment.

The base server is the location of the deployment configurations. Deployment configurations are XML-based files that determine how and to where to deploy files. The base server also maintains log files for each deployment and for general base-server activities.


• • • •••

The OpenDeploy Environment

Receiver

A receiver is a server with the receiver software installed on it. A receiver can only receive files as a target in the source/target relationship. Receiver are typically production servers outside the firewall that serve the deployed content to its intended audience; they do not need to redeploy the content files further.

Administration Server

The OpenDeploy administration server is responsible for managing and generating the browser-based OpenDeploy user interface, and for managing the Administrator and User role access to OpenDeploy, such as the ability to create and start deployments. The administration server does not send or receive files itself, but works with the source and target servers. The administration server software can reside with all the other OpenDeploy components on a single server or it can reside on a server separate from the base server or receiver software.

Reporting Server

The OpenDeploy reporting server publishes detailed summaries of events that take place on the base server and receiver servers in the OpenDeploy environment. These summary reports can then be accessed through the browser-based user interface, by entering a command-line utility, or integrated into other reporting structures.

ContentServices Foundation Access Service

The ContentServices Foundation (CSF) access service authenticates individuals who access OpenDeploy base servers or receivers through the browser-based user interface or Web services. The CSF access service software is installed as part of the administration package installation, seamlessly following the installation of the administration and reporting server software.

TeamSite

OpenDeploy can compare two areas, such as staging areas, editions, and workareas, and deploy the differences to a file system location or TeamSite area on the target server.


• • • •••


28

How OpenDeploy WorksThe OpenDeploy source server processes deployment configurations. These configurations determine the type of deployment being performed, as well as other functions and features OpenDeploy performs in the course of the deployment. The deployment configuration also specifies which target servers receive the deployed files.

Source-Target Relationship

A deployment of content files begins at the source server (the server sending the files) and ends at the target server (the server receiving the files).

Depending on the software you install on a server, an OpenDeploy server can act as both a source and target server, or as just a target server. Source servers are not restricted in the number of target servers available to them, providing the target server has the proper software installed and licensed. Similarly, a target server can receive deployments from any number of source servers.

Depending on the type of deployment taking place, the deployed files are either exactly the same for all targets, or customized based on a comparison of file differences between the source server and each target server.

Source Server

The source server is a server installed with the OpenDeploy base server software. The source server originates and manages all deployments. The source server maintains a list of all target servers to which it can deploy files. You can deploy files from one or more source file locations, which can be either file system locations or TeamSite areas.

Target Server

The target server is a server installed with the OpenDeploy base server or receiver software. Any such server in the OpenDeploy environment can receive deployed files, as long as the server is known to the source server and has declared itself available to receive deployments from the appropriate source servers.

Figure 1 shows the source/target relationship between a source server (with the base server software installed) and three target servers (one installed with the base server software and two installed with the receiver software).


• • • •••

How OpenDeploy Works

Figure 1 Single base server and multiple receivers

source server

(base server)

target server

(receiver)

target server

(base server)

target server

(receiver)

deployed files

The target servers that have the base server software installed are capable of redeploying the files they receive to another set of targets. A deployment originating from a single source server ca be redeployed several times to more targets automatically, which saves time and labor, and ensures content synchronicity among all the OpenDeploy servers. In this case, the server receiving the original deployment is a target server, but when it redeploys those files to a new set of target servers, it does so as a source server. This server must have the appropriate software installed and licensed to receive and redeploy files.


• • • •••


30

In Figure 2, one of the target servers for the first deployment has the base server software installed and can redeploy as a source server the files it received as a target server.

Figure 2 Redeploy files using multiple source servers

source server

(base server)target server/

source server

(base server)

target server

(receiver)

target server

(receiver)

target server

(receiver)

target server

(receiver)deployed files

redeployed files

Deployment Configurations

The criteria for how to determine which files are deployed is specified within a deployment configuration. An OpenDeploy source server can process any number of distinctly named deployment configuration files, each of which can deploy files to different target areas on different target servers under different conditions. A typical deployment configuration specifies:

source file locations

target servers

target file location

type of deployment

logging

use of external pre- and post-processing scripts

filters for limiting deployed files

rules for comparing files

rules for transmitting files

rules for setting file and directory permissions on deployed files


• • • •••


Figure 3 shows how a source server uses the information in a deployment configuration file to perform a deployment.

Figure 3 How OpenDeploy uses deployment configurations

source server target server

Files deployed to target server.

OpenDeploy references deployment configuration for instructions, including:

- targets

- deployment types

- criteria for deploying files

- pre- and post-processing scripts

File Location Definitions

From the source server, one or more source file locations can be specified for deployment to a single target file location. The grouping of one or more source file locations deploying files to a target is known in the deployment configuration as a definition. A definition is the basis of any deployment. Each definition must have a unique name that you can assign to it, either by editing the deployment configuration file or using the Deployment Configuration Composer.

Figure 4 shows how a single OpenDeploy server can deploy files from multiple source file locations (file system locations or TeamSite areas) to multiple target file locations on the same source and target server. Each definition can have one or more source file locations, but only a single target file location.


• • • •••


32

Figure 4 Definitions

Definition: MYDEFINITION1

Definition: MYDEFINITION2

D:\website\filesC:\dev\website\files

D:\website\reports/default/main/dev/EDITION


File Deployment Criteria

OpenDeploy determines file deployment criteria—whether a file or directory is to be deployed from the source server to the target server-based on one of the following methods.

comparing files between file system locations on a source and target server and determining the differences

comparing two TeamSite areas on the source server with TeamSite installed and determining the differences

deploying files referenced in a list of files without comparing them

Comparison-based Deployment Eligibility

A comparison-based deployment is the result of comparing one set of files with a second set of files. These file sets can be either file system locations on the source or target servers, or a pair of TeamSite areas within the same backing store on a source server.

The comparison criteria used to determine whether to deploy a given file are:

timestamp difference (by default, newer files are deployed, however, you can configure the deployment to deploy older files instead)

checksum difference (note that timestamp difference and checksum difference are mutually exclusive to each other)


• • • •••


type mismatch (a file and a directory share 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

Refer to “Deployment Features” in the OpenDeploy Deployment Configuration Guide for a complete description of all comparison-based deployability methods and criteria.

File List-based Deployment Criteria

File list deployments do not compare files or directories, but simply deploy the files from the source server based on a specified list of files. This list of files resides on the source server and is referenced in the deployment configuration.

Graphical User Interface

OpenDeploy provides a browser-based user interface with which you can create, schedule, start, and monitor deployments.

Figure 5 shows an example of the browser-based user interface. The navigation pane on the left presents you with full access to all the major task and monitoring windows. The details pane on the right displays the contents of the item in the navigation pane you selected.


• • • •••


34

Figure 5 OpenDeploy user interface

Some of the tasks you can perform using the OpenDeploy user interface are:

view the configuration file information for a selected deployment

create a new deployment and edit the configuration of an existing one

schedule deployments, either on a one-time basis, or recurrent by minute, hour, day, week, or month

start a deployment

monitor deployments, including logging, pending status, and success or failure

generate and view reports

Deployment TypesOpenDeploy uses one of the following methods for deploying files from the source server to the target servers:

directory comparison

file list

TeamSite comparison

payload adapter-based


• • • •••

Deployment Types

The following sections describe each method, including when each is best suited as your deployment choice.

Directory Comparison

Directory comparison deployments compare a specified directory on the source server and a corresponding the target server. New or updated files on the source server are copied to the target server. After the deployment is complete, the source and target servers’ files are the same. See “File Deployment Criteria” on page 32 for information on how OpenDeploy determines which files and directories are eligible for deployment.

You can include multiple file system locations in a deployment. The files residing in each of the specified locations are compared with the target files and the deployable files are sent to the target server.

If OpenDeploy is performing a fan-out deployment, it compares the source server’s files with each of the target servers’ files. The deployed files reflect the differences between the source server and each respective target server. That way, even if each of the target servers has a different set of files, following the deployment, they are all synchronized with the source server and with each other.

Directory comparison deployments provide a full synchronization of the content between the source and target servers. This is the most comprehensive way to ensure that the content on the source and target servers are identical. Directory comparison is also the most resource-demanding method for time and network bandwidth because file and directory information must be exchanged over the network to determine the source and target servers’ file differences.

File List

A file list-based deployment does not compare files. Instead, OpenDeploy moves files based on a predetermined list that specifies the files to deploy. The files and their paths in the list are in locations relative to the file system-based area specified in the deployment configuration. This list can be a fixed or static file, or it can be generated dynamically using a program-specific generation tool such as the TeamSite iwevents command-line tool.

The entries in the file list are influenced by the file system syntax of the server. Forward slashes (/) can be used for either Windows or UNIX servers: www/index.html

www/andre/index.html

www/products.html


• • • •••


36

Backslashes (\) are only permitted on Windows servers: www\index.html

www\andre\index.html

www\products.html

In these examples, www is a directory immediately subordinate to the area location on the source server as specified in the deployment configuration. For example, if the area specified for a source server is /webfiles, the entries in the file list example combined with the specified area end up being: /webfiles/www/index.html

/webfiles/www/andre/index.html

/webfiles/www/products.html

A file list deployment is simpler and more predictable than other deployments, which are comparison based. If a large number of small files is involved, a file list deployment can takes less of a toll on network resources than a directory comparison; it can process the deployment faster, however, if very large files are involved, deploying all the files specified in the file list may be less efficient than a comparison-based deployment where only the changed files are deployed.

By default any missing file in a filelist deployment is ignored and the deployment continues to the next file in the file list. A new attribute failOnMissingFile has been added to element <filelist>. For example, if in a filelist deployment has 100 files and 4 files are missing from the source, with attribute failOnMissingFile turned on, the deployment fails and the deployment error message is:

Following Files specified in filelist does not exist. Failing deployment...

LIB: 2010-01-07 10:51:05 ERROR [./missingfile01.txt]




LIB: 2010-01-07 10:51:05 ERROR: deploy-failed.

A typical configuration example is:<filelist area="/default/main/test/WORKAREA/shared" filePath="/tmp/filelist.txt" failOnMissingFile="yes" >

TeamSite Comparison

TeamSite comparison compares two TeamSite areas within the same backing store on the source server and deploys the differences to the target servers. The source server must have TeamSite installed and be configured to use this type of deployment. Workareas, staging areas, and editions can be specified for a TeamSite comparison deployment. See “File Deployment Criteria” on page 32 for information on how OpenDeploy determines which files and directories are eligible for deployment.


• • • •••

Deployment Types

In a TeamSite comparison, you specify the TeamSite area that contains the updated files to deploy. This area is typically the branch staging area or an edition. You must also specify another TeamSite area that contains a mirror image of the files on the target servers, typically a previously created edition. TeamSite compares the area with the updated files with the area with the existing target server files and deploys the differences to the specified target servers.

You can also configure OpenDeploy to determine the latest and next-to-latest TeamSite editions automatically, and to deploy the differences between them. This is a common method of integrating OpenDeploy and TeamSite.

Unlike a directory comparison deployment, the TeamSite comparison takes place solely on the source server. OpenDeploy assumes that the files in the previous area are identical to those on the target servers themselves. The deployed files are moved to the file system location on the target server specified in the deployment configuration.

Because the TeamSite comparison is done only on the source server, it is faster and less bandwidth-intensive than the directory comparison. No network traffic is generated before the file deployment occurs, however, TeamSite comparison is completely dependent on the source server having a perfect snapshot of the files residing on the target server. If files have been changed on the target server, it is up to you to ensure that the corresponding TeamSite area on the source server is updated as well. OpenDeploy can reverse-deploy from a target server to the source server, but it cannot independently determine when that is necessary.

Payload Adapter-based Deployment

A payload adapter-based deployment uses a payload adapter in conjunction with OpenDeploy to apply file selection criteria to a source file location. Files that meet the criteria are listed in a generated file manifest. OpenDeploy performs one of the following tasks with this file manifest.

compares the files in the manifest with the files in the target and, if appropriate, deploys them

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 deploy are accessible to OpenDeploy in a valid location. Supported locations include file system directories and TeamSite areas. Usage of payload adapter-based deployment includes 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 use of payload adapter-based deployment is to query a metadata repository for a list of files that meet specific criteria for deployment or deletion.


• • • •••


38

You can use your own payload adapters or use one of the adapters included with OpenDeploy. Depending on which adapter you use, information can be passed to the adapter from the deployment configuration at the time of deployment, either as a character string or via a query structure. The adapter can use this information in its processing, such as determining the location of the source data.

Query-based Adapters

A query-based adapter is a payload adapter that accepts the specification of deployment criteria based on a query syntax in the deployment configuration. A use case for this type of adapter is metadata-based deployment. The adapter converts the query structure into an appropriate call to a metadata repository. The files that match are grouped into a file manifest. OpenDeploy can subsequently apply one of the previous methods to the files in this manifest.

Content Delivery MethodsOpenDeploy allows a wide range of content delivery methods. The following sections describe the various methods you can use to deploy files between OpenDeploy servers.

Deployment to a Single Target

The simplest deployment of files is from the source server to a single target server. In Figure 6, the OpenDeploy source server references the deployment configuration for a single target deployment.

Figure 6 Deployment to a single target server


Files deployed to target server.

OpenDeploy references a single target deployment configuration.


• • • •••

Content Delivery Methods

This configuration specifies a forward deployment to the target server based on one of the following types of deployments:

directory comparison

TeamSite comparison

file list

payload adapter-based

The source server subsequently deploys those files to the target server, and the deployment completes successfully.

Deployment to Multiple Targets

This deployment configuration specifies to deploy a set of files to two or more target servers. This is called a fan-out deployment.

In Figure 7, the OpenDeploy source server A references the deployment configuration for a fan-out deployment to target servers A-1, A-2, and A-3.

Figure 7 Deployment to multiple target servers

source server A

target server A-1

Files deployed to target servers.

OpenDeploy references a fan-out deployment configuration.

target server A-2

target server A-3


• • • •••


40

Multitiered Deployments

A multitiered deployment uses one or more target OpenDeploy servers to deploy files to another set of servers, known as a tier. Each source server and its target servers represent a separate tier. Like fan-out deployments, multitiered deployments allow the automatic deployment of files to a wide range of recipient targets in your enterprise with little more effort than deploying to a single target server.

In Figure 8, the OpenDeploy source server mars performs a fan-out deployment as shown in Figure 7. Of the three target servers receiving the deployed files, venus is an OpenDeploy server with the base server software installed and is capable of performing deployments. Like mars, venus also references its own specified deployment configuration for its own deployment of files to mercury and neptune.

Figure 8 Multitiered deployment

mars

OpenDeploy on source server mars references a fan-out deployment configuration.

Files deploy to target servers.

OpenDeploy on target server venus references its own deployment configuration and redeploys received files to a new set of targets.

jupiter

saturn

venus

mercury

neptun

Files deployed to target servers.

Routed Deployments

Routed deployments are similar to multitiered deployments in that they permit content to be deployed across multiple tiers of base servers until they reach their final destinations. Each tier can deploy to base server and receiver targets, although only base servers can move content to the next tier.


• • • •••

Content Delivery Methods

Routed deployments differ from multitier deployments in that the base server at each tier does not require its own preinstalled deployment configuration file be in place prior to starting the deployment. Instead, a list of allowed tier-to-tier routes resides in the nodes configuration file of the source server originating the routed deployment. This list of route segments provides a road map that lists every allowed route from the originating source to each end target.

You can create route definitions that favor or avoid the movement of deployed content through certain servers. If you deploy very large amounts of content during times of peak network usage, you may not want to include a busy server, or one with lesser performance, in the route definition, however, that same server might be fine for routing deployments at other times.

Transactional Deployments

If one or more targets in a deployment fail to successfully receive the deployed files, you can configure OpenDeploy to automatically roll back the deployment that took place and restore all the target servers to their previous states. This feature is called a transactional deployment. This capability is vital if you have multiple production servers that must perfectly mirror each other.

Transactional deployments ensure that discrepancies between servers cannot exist as the result of a failed or problematic deployment. In the case of multitiered deployments, a transactional deployment rolls back the deployment across each tier until the entire enterprise returns to its previous state.

In Figure 9, mars ran a transactional deployment to venus that failed. Upon determination of the failure, OpenDeploy removes the portion of the deployment that arrived at venus and restores that server’s files to the previous state, effecting a rollback of the failed deployment.

Figure 9 Transactional deployment

OpenDeploy references a transactional deployment configuration.

mars venus

Deployment of files to target server is unsuccessful, and is reported back to OpenDeploy server.

OpenDeploy rolls back the failed deployment and restores target server files to their original state.

Transactional deployments require disk space equal to about three times the size of the deployed content, assuming the files are approximately the same size as those being replaced, however, space equal to about two times the size of the deployed content is temporary and is


• • • •••


42

automatically reclaimed after the transactional deployment completes. Performance time is slower than other deployment methods.

Specify a Target Quorum

In cases where you have multiple targets receiving a transactional deployment, it may be necessary for only a minimum number of those targets to receive their deployments for the entire deployment to be considered successful. This minimum number is called the quorum, and can be specified in the deployment configuration. Specifying a quorum prevents the entire transactional deployment from rolling back if an acceptable number of targets successfully receive their deployments.

Reverse Deployments

In some cases, the files on a production server may be changed before those on the development server. For example, production servers may generate the following types of data:

log files

data files created by an application server

assets uploaded through a Web server application

As the production server files generate, it may be important to deploy them back to the development server. Reverse deployments meet this requirement by moving files from a specified target server back to the source server. If the deployment type is a directory comparison, the target files are compared to the source files to determine which files to reverse deploy.

In Figure 10, the production server generated several production-related files that need to be deployed back to the development server. A reverse deployment configuration assigns the reverse source role to the production server and the reverse target role to the development server. The deployment takes place as any other deployment.


• • • •••

Access Rights and Privileges

Figure 10 Reverse deployment

OpenDeploy references a reverse deployment configuration.

New and updated files are reverse-deployed to the reverse

reverse target server

(development server)

reverse source server

(production server)

Base server initiates reverse deployment to reverse

Access Rights and PrivilegesIn an organization with thousands of files on hundreds of servers, deployment operations must be carefully managed and restricted only to authorized users. OpenDeploy makes a distinction between those who need authority to create and configure deployment configurations and those who need authority to start a specific deployment.

To meet this need, Administrator and User roles restrict which tasks an individual can perform through the OpenDeploy user interface or the Web services interface. These roles apply to which tasks can be performed involving specific servers and deployments. Each OpenDeploy user can be assigned to one or both of these roles.

Administrator Role

The Administrator role allows full access to OpenDeploy configuration and functionality. The Administrator role can perform any deployment operations, such as designating which users can invoke given deployments and schedule deployments.

User Role

The deployment User role authorizes an individual to perform deployment operations on specific deployments (previously created by an Administrator). The User role can perform tasks such as starting and canceling authorized deployments and editing authorized schedules.


• • • •••


44
• • • •••

Chapter 2

Get Started

This chapter provides instructions on how to start your OpenDeploy server and configure it for use.

Start OpenDeployOpenDeploy runs by starting its services or daemons. Start the services or daemons in the following order:

base server or receiver

administration server

SNMP server

The method of starting these service and daemons differs based on the type of platform on which it operates.

Windows

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

rebooting

starting the OpenDeploy services from the Services window

starting from the command line


• • • •••

Chapter 2: Get Started

46

Start by Rebooting

After the OpenDeploy software is successfully installed on the server, the OpenDeploy services automatically start on rebooting. Be sure to have the bootstrap administrator configured before rebooting. See “Configure the Bootstrap Administrator” on page 136 for more information.

Start from the Services Window

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

OpenDeploy services can vary depending on which software components you installed. Table 1 shows the OpenDeploy services and their corresponding software components.

To start the OpenDeploy services

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

2. Right-click Interwoven OpenDeploy 720 Service and select Start from the shortcut menu.

3. Right-click Interwoven OpenDeploy UI Admin and select Start from the shortcut menu.

4. (optional) Right-click Interwoven OpenDeploy 720 SNMP Service and select Start from the shortcut menu.

The optional OpenDeploy 720 SNMP service allows you to monitor the status of an OpenDeploy server using an SNMP-enabled network management tool. See “SNMP” on page 166 for more information on this feature.

The services listed in Table 1 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 have the marketing instance running, the Services window opens as in Table 2.

Table 1 OpenDeploy services

Service Software

Interwoven OpenDeploy 720 Service OpenDeploy base server or receiver

Interwoven OpenDeploy UI Admin Administration server

Interwoven OpenDeploy 720 SNMP Service

SNMP server


• • • •••

Start OpenDeploy

To start a service associated with a given instance, right-click that instance’s service and select Start from the shortcut menu.

Start from the Command Line

To start one or more OpenDeploy services from the Windows command line

1. Open a command-line dialog box and type the following command to start the OpenDeploy service: net start iwodserver

2. Type the following command to start the OpenDeploy UI Admin service: net start iwodadmin

3. Type the following command to start the SNMP service: net start iwodsnmp

When you create additional instances of your OpenDeploy base server or receiver, the instance name appends to the iwodserver and iwodsnmp commands. For example, to start an OpenDeploy or SNMP daemon associated with the server marketing instance, the start commands for the servers are: net start iwodservermarketing

net start iwodsnmpmarketing

UNIX

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

Reboot the server. After OpenDeploy software is successfully installed, OpenDeploy daemons automatically start upon rebooting the server. Be sure to have the bootstrap administrator configured before rebooting after installing your OpenDeploy software. See “Configure the Bootstrap Administrator” on page 136 for more information.

Table 2 Services for multiple instances of OpenDeploy

Service

Interwoven OpenDeploy 720 Service

Interwoven OpenDeploy 720 Service: marketing

Interwoven OpenDeploy UI Admin


Interwoven OpenDeploy 720 SNMP Service: marketing


• • • •••


48

Type 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 from the location of the OpenDeploy start program.

Navigate to the init.d Directory

Starting the OpenDeploy daemons on a UNIX host requires navigating to the init.d directory. Note that the directory resides in a different path depending on the platform. It can be:

od-home/etc/init.d

/etc/init.d

od-home/etc/rc.d/init.d

/etc/rc.d/init.d.

Start the Servers

To start the base server or receiver software for UNIX

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

2. Start the OpenDeploy base server or receiver software by typing the following command at the prompt: ./iwodserver start

3. Start the administration server by typing the following command at the prompt: ./iwodadmin start

4. (Optional) Start the OpenDeploy SNMP software by typing the following command at the prompt: ./iwodsnmp start

The optional OpenDeploy SNMP service allows you to monitor the status of an OpenDeploy server using an SNMP-enabled network management tool. See “SNMP” on page 166 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 iwodserver and iwodsnmp commands. For example, to start an OpenDeploy or SNMP daemon associated with the server instance marketing, the start commands for the servers are:

./iwodservermarketing start ./iwodsnmpmarketing start


• • • •••

Stop OpenDeploy

NOTE

The TeamSite command-line tool iwreset does not restart OpenDeploy.

Start the User Interface

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

Stop OpenDeployOpenDeploy is stopped by terminating its services or daemons. Stop these services or daemons in the following order:

1. SNMP server

2. administration server

3. base server or receiver

The method of stopping these service and daemons differs depending on the type of platform on which it operates.

Windows

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


• • • •••


50

Stop from the Services Window

The services in Table 3 correspond to the OpenDeploy software components.

To stop the OpenDeploy services from the Services window

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

2. Right-click Interwoven OpenDeploy 720 SNMP Service and select Stop from the shortcut menu to stop the SNMP server.

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

4. Right-click the Interwoven OpenDeploy 720 Service and select Stop from the shortcut menu to stop the base server or receiver software.

The services listed in Table 3 and in the steps to stop OpenDeploy represent the initial instance of OpenDeploy. If you have multiple instances of OpenDeploy running, the instances are represented in the Services window. For example, if you have the instance marketing running, the Services window opens as shown in Table 4.

To stop a service associated with a given instance, right-click that instance’s service and select Stop from the shortcut menu.

Table 3 OpenDeploy services

Service Software

Interwoven OpenDeploy 720 SNMP SNMP server

Interwoven OpenDeploy UI Admin Administration server

Interwoven OpenDeploy 720 Service OpenDeploy base server or receiver

Table 4 Services for multiple instances of OpenDeploy

Service

Interwoven OpenDeploy 720 Service

Interwoven OpenDeploy 720 Service: marketing

Interwoven OpenDeploy UI Admin


Interwoven OpenDeploy 720 SNMP Service: marketing


• • • •••

Stop OpenDeploy

Stop from the Command Line

To stop one or more OpenDeploy services from the Windows command line

1. Open a command line dialog box and type the following command to stop the SNMP service: net stop iwodsnmp

2. Type the following command to stop the OpenDeploy UI Admin service: net stop iwodadmin

3. Type the following command to stop the OpenDeploy service: net stop iwodserver

To stop an OpenDeploy server or SNMP service associated with a given instance (for example, marketing), you include the instance’s name in the command, for example: net stop iwodservermarketing

net stop iwodsnmpmarketing

UNIX

To stop the OpenDeploy daemons on a UNIX server

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

2. Stop the SNMP server by typing the following command at the prompt: ./iwodserversnmp stop

3. Stop the administration server by typing the following command at the prompt: ./iwodadmin stop

4. Stop the base server or receiver software by typing the following command at the prompt: ./iwodserver stop

To stop an OpenDeploy server or SNMP daemon associated with a given instance (for example, marketing), you include the instance’s name in the command, for example: ./iwodsnmpmarketing stop

./iwodservermarketing stop


• • • •••


52

Run Multiple Instances of OpenDeployYou can run multiple instances of the same release of an OpenDeploy base server or receiver on your host. Running multiple instances of OpenDeploy provides advantages such as:

running a separate receiver as a unique non-root user within a hosting service facility allows the hosting service provider to dedicate a separate receiver to each customer who deploys to the hosting service

using a different encryption setup for each service or daemon, thereby providing an added measure of security

setting up a backup IP for network failures. Each receiver instance can listen on a different IP address on a host that has multiple network interfaces.

segmenting operations according to organizational policy. For example, different Web sites on a single server can be managed by different divisions, each of which has its own OpenDeploy configuration. This allows each division to configure its own instance of OpenDeploy.

limiting access to source areas. For example, you can limit access of a deployment job to specific source areas. One way to achieve this is to run multiple base servers as different users and restrict file system access based on those users.

migrating to new releases of OpenDeploy software easily. The new version can run beside the earlier version and allow you to continue to run older deployment jobs until the new installation is approved for production use. This arrangement provides a fallback position in the event the new installation fails for any reason.

separating DAS tasks from OpenDeploy tasks. For performance reasons, it may be desirable to set up two base server instances:

to handle DAS events exclusively

to service deployments to staging and production servers

Use of multiple instances is not supported by the EasyDeploy base server software. To use this feature, you must upgrade to the full-feature base server software.

Installation

Running multiple instances of OpenDeploy does not require installing the software more than once on the host. No additional installation tasks are required to run OpenDeploy with multiple instances than with a single instance. When you create a new instance, the required configuration files and file directories are automatically created. See “Create an Instance” on page 57 for more information.


• • • •••

Run Multiple Instances of OpenDeploy

You can install and run only one release of the legacy OpenDeploy 5.x software on the same host that contains the current release. Refer to the OpenDeploy Release Notes for a list of supported legacy OpenDeploy releases. Legacy OpenDeploy releases can only run a single instance.

Directory Structure

When an instance is created, OpenDeploy generates a supporting directory structure for that instance in the following location on the host: od-home/inst/instance_name/*

where instance_name is the unique name you assigned that instance when you created it. For example, if you create the instance marketing, the associated directory structure resides in: od-home/inst/marketing

Within this directory structure are all the configuration files necessary to support that instance. These files include a dedicated base server or receiver file (by default odbase.xml or odrcvr.xml), a nodes configuration file (by default odnodes.xml), and a service configuration file (deploy.cfg). Dedicated run-time data is also stored within this structure; for example, schedules and reporting event messages.

The settings of the configuration files are determined in part by the preconfigured properties file that you must provide before creating a new instance. This properties file contains a variety of settings that OpenDeploy uses to assign values to the configuration files. You can modify any configuration file for a given instance. See “Properties File” on page 54 for more information.

Services and Daemons

Separate OpenDeploy and SNMP Windows services or UNIX daemons are generated when an instance is created. These services and daemons include the instance name in them. You must enable these instance-specific services or daemons to start the associated instance and disable them to stop the instance. You can also configure these services or daemons to be disabled or enabled when the host starts.

Instance Names

OpenDeploy assigns the name initial to the first instance of OpenDeploy following the product installation. The name conf is also a reserved term. As a result, you cannot assign the name initial or conf to any user-created instance.


• • • •••


54

Each instance you create must have a unique name, which you provide at the time of creation. You can assign any unique name (other than initial and conf) to each instance using any combination of alphabetic and numeric characters. No other instance can share the name. Dashes (“-”) and underscores (“_”) are allowed in instance names, however, spaces are not allowed. Instance names are case-sensitive on UNIX and case-insensitive on Windows. If your OpenDeploy environment includes a mix of UNIX and Windows hosts, always specify the case-sensitive version of an instance name.

Properties File

With the exception of the initial instance, which uses default properties, each OpenDeploy instance has an associated properties file. This is a user-defined configuration file that must have the following naming syntax: instance_name.cfg

where instance_name is the name of the instance associated with the properties file. For example, if you have the instance marketing, the associated properties file is marketing.cfg.

All properties files must reside in the following location. od-home/inst/conf

A properties file contains a series of name=value pairs that are used by the OpenDeploy instance tool to configure automatically all the associated configuration files when a new instance is created. For example: MYTARGETPORTNUMBER=20024

MYRMIREGISTRYPORT=9183

MYADMINRMIPORT=24171

MYREPORTINGRMIPORT=24178

MYCLTPROXYPORT=3444

DOMAIN\\\\USER=hostname\\\\Administrator

ENABLEINSTANCE=yes

ENABLEREPORTING=yes

MYDATABASEDEPLOYPORT=2351

MYWEBSVCHTTPPORT=9283

MYWEBSVCHTTSPPORT=9284

ENABLESNMPINSTANCE=yes

MYSNMPREQUESTPORT=161

MYSNMPTRAPPORT=162

When you create the properties file for use in creating OpenDeploy instances, you must modify certain attribute values, such as the port numbers, giving them unique values. Other properties, such as the bootstrap administrator, are optional. You can provide your own values for these attributes, or comment them out and let OpenDeploy use the default values.


• • • •••


OpenDeploy provides a template to base your customized properties files on. This template file in the following location: od-home/inst/conf/examples/instance.cfg

Properties File Attributes

This section describes the properties file attributes. The attributes that must change for each new instance are noted as “(required)”. The attributes that you can change at your discretion are noted as “(optional)”. Optional attributes must have the associated comment symbol (#) removed to enable the specified value.

For the TCP and UDP port attributes, the valid port range is 1–65535, with 1–1024 reserved for the operating system. This value must be a unique port number (that is, not in use by any other OpenDeploy instance or any other program). TCP and UDP ports can share the same port number without conflict.

There is no default value. If a port number is missing or invalid, the instance creation fails. If the ports are in use at runtime, the instance fails to start correctly.

MYTARGETPORTNUMBER (required) is the TCP port on which OpenDeploy instance listens for incoming deployments.

MYRMIREGISTRYPORT (required) is the TCP port on which the OpenDeploy RMI registry listens.

MYADMINRMIPORT (required) is the RMI connection TCP port used by OpenDeploy for the administration server.

MYREPORTINGRMIPORT (required) is the RMI connection TCP port used by OpenDeploy for the event reporting server.

MYCLTPROXYPORT (required) is the TCP port to which the CLT proxy binds. The CLT proxy is a socket listener that by default binds on localhost and only allows localhost requests.

MYOPENJMSPORT (required) is the TCP port on which the JMS messenging server binds for reporting.

MYJMSJNDIPORT (required) is the JNDI port used to find the JMS messenging server.

MYSNMPREQUESTPORT (required) specifies the request UDP port of the SNMP agent instance.

MYSNMPTRAPPORT (required) specifies the UDP trap port of the SNMP agent instance.

DOMAIN\\\\USER (optional) is the base server or receiver bootstrap user name.

Windows domain-name\\\\username or

UNIX username


• • • •••


56

NOTE

Four backslashes (\\\\) are required to separate the domain and the user name.

See “Configure the Bootstrap Administrator” on page 136 for information on this feature.

ENABLEINSTANCE (optional) specifies whether (yes or no) this instance of OpenDeploy starts automatically when the host starts. The default value is no. If a valid choice is not specified, OpenDeploy uses the default value.

You can change this setting after the instance is created through the Service window in Windows or by running the iwodinsttool command-line tool.

ENABLEREPORTING (optional) specifies whether (yes or no) the event reporting feature is enabled on this OpenDeploy instance. The default value for a base server is yes; the default value for a receiver is no. If a valid choice is not specified, OpenDeploy uses the default value.

MYDATABASEDEPLOYPORT (optional) is the TCP port to which the DAS listener binds.

MYWEBSVCHTTPPORT (optional) is the TCP port to which the Web services HTTP listener binds.

MYWEBSVCHTTPSPORT (optional) is the TCP port to which the Web services HTTPS listener binds.

MYWEBSVCODCERT (optional) is the HTTPS certificate name for use by Web services.

MYWEBSVCODCERTPD (optional) is the HTTPS Certificate password for use by Web services.

ENABLESNMPINSTANCE (optional) specifies whether (yes or no) the SNMP agent for this instance starts automatically when the host starts. The default value is no. If a valid choice is not specified, OpenDeploy uses the default value.

MYENCODING (optional) is the file encoding to use.

Define OpenDeploy Instances

Multiple instances of OpenDeploy are defined using the iwodinsttool command-line tool. Various options are associated with the iwodinsttool command-line tool. Here is a list of these options, along with the usage syntax:

iwodinsttool -h | -v

iwodinsttool (-create | -remove | -enable | -disable |-enableSNMP | -disableSNMP) [-odinst instName]

-h Displays usage information.


• • • •••


The iwodinsttool command returns the following codes about the status of the action taking place:

0: succeeded

1: failed

Using the iwodinsttool command-line tool requires specifying the option for the task you want to perform (for example -create or -remove) with the specified instance (-odinst instance_name). If you do not specify the instance name, OpenDeploy defaults to the original instance intial.

NOTE

You cannot create or remove the initial instance.

Create an Instance

NOTE

You must have an associated properties file present before you can create an instance. See “Properties File” on page 54 for information.

-v Displays version information.

-create Creates a new instance using the properties file named instName.cfg in the od-home/inst/conf directory, where instName is the name of the instance to be created (specified by the -odinst argument)

-remove Removes a specified existing instance.

-enable Enables the automatic startup of the instance when the host starts.

-disable Disables the automatic startup of the instance when the host starts.

-enableSNMP Enables the automatic startup of the associated SNMP service or daemon when the host starts.

-disableSNMP Disables the automatic startup of the associated SNMP service or daemon when the host starts.

-odinst instName Specifies the OpenDeploy server instance name. The default value is initial.


• • • •••


58

You cannot create an OpenDeploy instance with the name initial or conf. The original OpenDeploy instance is assigned the name initial, and conf is a reserved term.

To create an instance

1. Create a properties file for the instance. See “Properties File” on page 54 for information.

2. Do any one of the following for Solaris on x86 and AIX platforms:

a. Open the file od-home/lib/template/etc/deploy.cfg_templ in an appropriate editor.

b. Uncomment the line teamsite.version: 6.5.0.

c. Save the file and close the editor after making the changes.

For other platforms, go to step 3.

3. Navigate to: od-home/bin

4. Type the following command at the prompt: iwodinsttool -create -odinst instance_name

where instance_name is the unique name of the instance. For example, to create the instance marketing, type: iwodinsttool -create -odinst marketing

Remove an Instance

If you want to save any files associated with the instance, move or copy them to another location before removing the instance. For a more systematic backing up of OpenDeploy files, see “Back up OpenDeploy Files” on page 162.

You cannot remove the original OpenDeploy instance initial, however, you can disable the initial instance. See the next section for more information.

To remove an instance


2. Type the following command at the prompt: iwodinsttool -remove -odinst instance_name

The instance and its supporting directory structure are completely removed.

Disable an Instance

Disabling the instance prevents the associated OpenDeploy service or daemon from running when the server starts. This feature allows you to enable the instance at a later time, which


• • • •••


provides an alternative to removing the instance completely. You cannot assign the name of an existing instance that is disabled to a new instance.

To disable an instance


2. Type the following command at the prompt: iwodinsttool -disable -odinst instance_name

Enable an Instance

Enabling a disabled instance allows the associated OpenDeploy service or daemon to start when the server starts.

To enable a disabled instance


2. Type the following command at the prompt: iwodinsttool -enable -odinst instance_name

Disable SNMP

Disabling an instance’s SNMP prevents the associated SNMP service or daemon from starting automatically when the server starts.

To disable an instance’s SNMP


2. Type the following command at the prompt: iwodinsttool -disableSNMP -odinst instance_name

Enable SNMP

Enabling an instance’s disabled SNMP allows the associated SNMP service or daemon to start automatically when the server starts.

To enable an instance’s disabled SNMP


2. Type the following command at the prompt: iwodinsttool -enableSNMP -odinst instance_name


• • • •••


60

Start and Stop an Instance

You can start and stop an instance in a manner similar to starting and stopping other OpenDeploy services and daemons. See “Start OpenDeploy” on page 45 and “Stop OpenDeploy” on page 49 for information.

Configure Instances as Target Nodes

Each instance is a potential target node. You can deploy files to multiple OpenDeploy server instances on the same host as if they were servers on separate hosts. Each instance must be configured in the senders nodes configuration file. See “Multiple Instances” on page 148 for information on configuring OpenDeploy instances in the nodes configuration file.

Use Database Auto-Synchronization

If you run multiple instances of the OpenDeploy base server, you can only use database auto-synchronization (DAS) with one of the instances. All other deployments are supported through all base server instances. Refer to “Database Auto-Synchronization” in the Database Deployment for OpenDeploy Administration Guide for more information on this feature.

If additional base server instances are inadvertently configured for DAS, a warning appears in their odbase.log files stating that either TeamSite is not installed or the TeamSite event server did not start.


• • • •••

Run 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 the operating system.

Run 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

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

2. Stop the Interwoven OpenDeploy Service. See “Stop OpenDeploy” on page 49 for information on stopping OpenDeploy services.

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

Windows 2000: Click Action > Properties to open the Properties dialog box. 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 type the account user and password information in the appropriate text boxes.

5. Click OK and close the Services window.

6. Restart the OpenDeploy service you previously stopped. See “Start OpenDeploy” on page 45 for information.

Run OpenDeploy on UNIX as Non-Root

You can convert an OpenDeploy base server or receiver on UNIX to run as non-root.

To convert an OpenDeploy base server or receiver on UNIX to run as non-root

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


• • • •••


62

2. configure OpenDeploy to start as a specified non-root user

Change 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 runs as that user and group ID, it can write and access the necessary files. You must be the root user to install OpenDeploy and subsequently to run the iwodnonroot command.

Here is a list of the iwodnonroot usage syntax:

If the optional od-home argument is not specified, iwodnonroot looks up the od-home from the following file: /etc/defaultiwodhome

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

To prepare OpenDeploy on UNIX to run as non-root

1. Stop the OpenDeploy base server or receiver daemon. See section “Stop OpenDeploy” on page 49 for information on stopping OpenDeploy daemons.


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

iwodnonroot owner group

To convert OpenDeploy to run under the user ID jdoe and group ID tech_pubs, type:iwodnonroot jdoe tech_pubs

To include the od-home location, type:iwodnonroot jdoe tech_pubs /usr/local/OpenDeployNG

iwodnonroot -h | -v

iwodnonroot owner group [od-home] [-odinst instName]



owner User name or ID

group Group name or ID

od-home Full path to the OpenDeploy home directory.

-odinst instName Uses OpenDeploy server instance instName.


• • • •••


4. Make sure od-home/jre/bin/java is world executable. If it is not, issue the following command:chmod 0775 od_home/jre/bin/java

where, od-home is the path to OpenDeploy home.

5. Start the OpenDeploy service as the non-root user. See section “Start OpenDeploy” on page 45 for information on starting OpenDeploy daemons.

6. After the OpenDeploy service is configured to be run as a non-root user, the OpenDeploy service, for that instance should not be run as root user. In case, you start the OpenDeploy service as root user from the command line after configuring to be run as non-root user, the iwodnonroot command needs to be re-run as root user the same way as described in steps 1 to 3.

7. To configure the OpenDeploy service to start as this non-root user automatically at boot time, continue with the following section “Automatically Start OpenDeploy as a Non-Root User” on page 63 before rebooting. Otherwise, if you reboot, the OpenDeploy service starts again as root user.

Automatically Start OpenDeploy as a Non-Root User

The OpenDeploy start 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 “Change Permissions to a Non-Root Ownership” on page 62 before continuing with this procedure.

You must be root to perform the following procedure.

The procedure for configuring the OpenDeploy start script can vary depending on the operating system. The procedure for Solaris is described here. If you use 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

1. Navigate to: /etc/init.d

2. Create the symbolic link iwodserver_boot by typing the following command at the prompt: ln -s /etc/init.d/iwodserver_boot

3. Create the file /etc/init.d/iwodserver_boot_wrap with a text editor. Include the following lines:#!/bin/sh

# Wrapper script to start/stop OpenDeploy as non-root_user at boot time

PATH="$PATH":.:/usr/sbin:/sbin:/usr/bin

su <non-root_user> -c "/etc/init.d/iwodserver_boot $1 -nonrootstartup `basename $0`"


• • • •••


64

where, <non-root_user> is an alternate user name, for example jdoe.

4. Change the permission by typing the following command at the prompt: chmod 775 /etc/init.d/iwodserver_boot_wrap

5. Navigate to:

Solaris: /etc/rc3.d

RedHat Linux: /etc/rc5.d

AIX: /etc/rc.d/rc2.d

HP-UX: /sbin/rc3.d

6. Update the symbolic links by typing the following commands at prompt:

Solaris and RedHat Linux:rm S80iwodserver

ln -s /etc/init.d/iwodserver_boot_wrap S80iwodserver

AIX:rm S21iwodserver


HP-UX: rm S998iwodserver


7. Navigate to:

Solaris: /etc/rc2.d

RedHat Linux: /etc/rc2.d

AIX: /etc/rc.d/rc6.d

HP-UX: /sbin/rc1.d

8. Update the symbolic links by typing the following commands at the prompt:

Solaris and RedHat Linux: rm K80iwodserver

ln -s /etc/init.d/iwodserver_boot_wrap K80iwodserver

AIX:rm K80iwodserver


HP-UX: rm K998iwodserver


9. For Linux platform, make sure that the directory /var/lock/subsys has permission set to 775.


• • • •••


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

To start and stop OpenDeploy after booting, use the following script: /etc/init.d/iwodserver

rather than the script: /etc/init.d/iwodserver_boot_wrap

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

Restrictions while 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 ownership of the running OpenDeploy process. Refer to “Enabling UNIX-Based Deployments When Extended ACLs Are Present” in the OpenDeploy Deployment Configuration Guide for more information.


• • • •••


66

NOTE

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

Refresh the OpenDeploy ServerAny time you modify certain elements in the OpenDeploy server configuration files, you must reset the OpenDeploy base server or receiver service or daemon to accept the changes. You can refresh your OpenDeploy server without rebooting or manually restarting individual services or daemons by using the iwodcmd serverreset command-line tool. The iwodcmd serverreset 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 read without having to stop your services or restart your host.

The iwodcmd serverreset command-line tool does not cause the configuration to refresh if deployments in progress at the time the command runs.

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

allowedHosts

allowedDirectories

logRules

You cannot refresh the following elements and their attributes in the base server and receiver configuration file:

localNode

initiatorProperties

listenerProperties

transportProperties

schedulerProperties

Changes made to the encryption setting (SSL or keyfile) in the base server or receiver configuration file are not refreshable. See “Encryption” on page 258 for more information. To make the server read and implement changes in these elements, you must restart the OpenDeploy services or daemons. Refer to the OpenDeploy Reference for descriptions of these elements and their attributes.


• • • •••

Refresh the OpenDeploy Server

To refresh your OpenDeploy server’s configurations


2. Reset the OpenDeploy services by typing the following command at the prompt: iwodcmd [-odinst instName] serverreset

Various options are associated with the iwodcmd serverreset command-line tool. Here is a list of the options, along with the usage syntax:

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

iwodcmd [-odinst instName] serverreset -q

iwodcmd [-odinst instName] serverreset -clearpath pattern



-q Disables messages generated when active deployments are in progress when the command runs.

-clearpathreg pattern Clears the path registry of paths matching the specified pattern. The pattern argument is a path string with support for (“*”) wildcards. You must include the entire pattern value in quotes if any wildcards are included, for example: -clearpathreg "/a/b/c/*" clears all path entries in the registry with the parent path /a/b/c including a/b/c itself. If no pattern is specified, all paths are cleared.



• • • •••


68

OpenDeploy User InterfaceThe user interface (see Figure 11) enhances your ability to perform and monitor OpenDeploy tasks anywhere in the enterprise.

Figure 11 OpenDeploy user interface

All you need 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. The graphical monitoring and scheduling features are an advantage in managing deployments, however, more advanced features and configurations still require you to work directly with configuration files and command-line tools.

When you start OpenDeploy for the first time after installing it, you must follow the procedures for first time startup 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.


• • • •••

OpenDeploy User Interface

Browser Refresh Requirements

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

Access the User Interface

To access the OpenDeploy user interface, navigate the 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 upon installing the administration server software. For example, if your administration server host is named andromeda and you typed the administration port number 8081, the URL to access the user interface is: http://andromeda:8081/iw/opendeploy/login

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


• • • •••


70

Log In

Starting the user interface displays the login dialog box (see Figure 12).

Figure 12 OpenDeploy login dialog box

To log in to OpenDeploy

1.Type the following information in the login dialog box:

Username: Type your user name for authentication 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: Type the password associated with the user name you provided.

Server: Select the OpenDeploy base server or receiver that you want to access. You must have an Administrator or User role on the server you select. See “Select the Host” on page 71 for additional information.

Role: Select either admin or user depending on your role on the selected server. See “Roles and Authorization” on page 117 for more information. When you log in for the first time as the bootstrap administrator, see “First-Time Login as Bootstrap Administrator” on page 72.

2. Click Login, the administration server authenticates your login information with the ContentServices Foundation (CSF) access service.


• • • •••

OpenDeploy User Interface

This server contains user authentication information for your OpenDeploy environment. If the CSF access service successfully authenticates the user login, the administration server 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 they match, the login succeeds.

Select the Host

When you log in, you must select an OpenDeploy base server or receiver that is running in the OpenDeploy environment. By default, the Host list in the Login dialog box 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, you must add the desired server to the administration server’s odservers.cfg file. The odservers.cfg file resides in: admin-home/odadmin/config

Open the file with a text editor and add a node element entry within the nodeSet element for the OpenDeploy server. For example: <nodeSet>

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

</nodeSet>

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

name is the logical name of the OpenDeploy server. This is the name that appears in the Host list in the Login dialog box.

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

port is the RMI registry port of the OpenDeploy server.

Save the odservers.cfg file and close it, and then restart the administration server. Now you can select the OpenDeploy server you want from the Host list in the Login dialog box. See “Start OpenDeploy” on page 45 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 72 for more information.


• • • •••


72

First-Time Login as Bootstrap Administrator

The first time you access an OpenDeploy base server or receiver with the browser-based user interface, either when OpenDeploy is first installed or after the creation of a new OpenDeploy instance, you must log in as the bootstrap administrator to gain full administration access. If you have not configured a bootstrap administrator, you must do so before you can log in. See “Configure the Bootstrap Administrator” on page 136 for more information.

Select the Administrator role when you log in as the bootstrap administrator. You can only log in as the bootstrap administrator under the admin role. If you log in with a user role, the login fails.

Timeout Setting

OpenDeploy includes a timeout feature for the user interface. This security measure prevents unauthorized access to an OpenDeploy user interface window that is idle past the timeout period. Then, users who attempt to perform any task through the user interface must log in. The default timeout period is in milliseconds, with the default value being 86400000 (24 hours).

To change the timeout value of the OpenDeploy user interface

1. Open the framework.properties file with a text editor: This file resides in: 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 number of milliseconds the login session can remain idle before a new login is required.

3. Save and close the file.

4. Restart the administration server service or daemon. See “Start OpenDeploy” on page 45 for more information. The OpenDeploy user interface automatically times out when idle past the number of milliseconds you entered.

OpenDeploy Server ManagementYou 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 listed OpenDeploy server as long as you have the proper access and permissions and the OpenDeploy server can perform the given


• • • •••

OpenDeploy Server Management

task. You must add each OpenDeploy server you want to manage into the Servers dialog box (see Figure 13). You can also modify and delete existing servers from this dialog box.

Figure 13 Servers dialog box

The Servers dialog box contains the following attributes:

Name column displays the logical name of the server.

Address column displays the resolvable host name or IP address of the server.

Port column displays the port used for sending and receiving deployments.

Edit button: Click to modify the name, address, or port information for the corresponding server.

Delete button: Click to remove the server from the user interface.

New Server button: Click to display the Edit Server dialog box, where you can add a new server.

Add an OpenDeploy Server

To add an OpenDeploy server to the user interface

1. Select Servers > View Servers to display the OpenDeploy Servers dialog box (see Figure 13). You can see the listed OpenDeploy servers with their resolvable host name or IP address, and RMI registry port number.

2. Click New Server to display the New Server dialog box (see Figure 14).

Figure 14 New Server dialog box


• • • •••


74

3. Type the following information about the new server in the New Server dialog box.

Name box: Type a logical name for the OpenDeploy server you are adding.

Address box: Type the resolvable host name or IP address.

Port box: Type the port number used to send and receive deployments.

4. Click Save to add the new server. The OpenDeploy Servers dialog box reopens with the newly added server (see Figure 15).

Figure 15 OpenDeploy Servers dialog box with the new server

You can click Cancel to discard any changes or additions, and return to the OpenDeploy Servers dialog box.

Change Server Information

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

To change the information of a selected OpenDeploy server

1. Select Servers > View Servers to display the OpenDeploy Servers dialog box (see Figure 13 on page 73).

2. Click the Edit button that corresponds to the OpenDeploy server whose information you want to change. The Edit Server dialog box opens (see Figure 16).

Figure 16 Edit Server dialog box


• • • •••

OpenDeploy Server Management

3. The Edit Server dialog box contains configuration items related to OpenDeploy servers. To you edit an existing server, modify these items as needed.

Name box: Modify the logical name for the OpenDeploy server you are adding.

Address box: Modify the resolvable host name or IP address.

Port box: Modify the port number used to send and receive deployments.

4. Make changes as needed and click Save. The OpenDeploy Servers dialog box reopens, reflecting the changes you made to the server.

Alternatively, click Cancel to discard any changes or additions, and return to the OpenDeploy Servers dialog box.

Delete OpenDeploy Servers

You can delete servers from the OpenDeploy user interface through the OpenDeploy Servers dialog box. You can only delete from the list of servers in the user interface; you cannot delete any OpenDeploy software from the server. You can add any server you previously deleted.

To delete a selected OpenDeploy server from the user interface

1. Select Servers > View Servers to display the OpenDeploy Servers dialog box (Figure 13 on page 73).

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

3. Click OK to confirm that you want to delete that selected server. The OpenDeploy Servers dialog box refreshes, no longer displaying the server you just deleted.


• • • •••


76

Monitor Server Logs and Configurations

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

Figure 17 Server Management window

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


• • • •••

Server Management Window

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

Server Management Window Selected Server list: Select the name of the OpenDeploy server whose server management

information you want to view.

View Log button: Click to display the base server or receiver log of the host you selected.

Server Config displays the name of the base server or receiver configuration file being used by the selected host. Default is odbase.xml or odrcvr.xml.

Nodes Config displays the name of the nodes configuration file being used by the selected host. Default is odnodes.xml.

Event Reporting Config displays the name of the event reporting configuration file being used by the selected host. Default is eventReportingConfig.xml.

JMS Config displays the name of the JMS configuration file being used by the selected host. Default is jmsConfig.xml.

Refresh Server button: Click to refresh the server with any changes you made to the following areas in the host configuration files:

Allowed hosts

Allowed directories

Log rules

Upload File box: Type the path to the host configuration file you want to upload to the selected host. Alternatively, you can click Browse to navigate to the file.

Browse button: Click to navigate to the location of the host configuration file you want to upload.

Upload button: Click to upload the selected host file configuration. The file you select is copied to the od-home/etc directory of the selected host.

Overwrite check box: Select to allow an uploaded configuration to overwrite an existing configuration with the same file name. If this box is clear, the upload cannot occur.

View File list: Select the host configuration file whose source code you want to view.

Configuration window displays the source XML code for the host configuration file you selected.


• • • •••


78

View the Base Server and Receiver Log Files

You can access and view the base server and receiver log files from the Server Management window.

To view the base server and receiver log files

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 opens displaying the OpenDeploy Log Viewer window that contains the base server or receiver log file of the server you chose.

Upload Modified Server Configuration Files

The Server Management window provides the ability to upload any of the following server configuration files from your local computer into the od-home/(od-instance)/etc directory of the selected server.

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)

Any file you upload must be a valid XML file that follows its associated configuration DTD.

For example, to add or modify the base server file of a given OpenDeploy server, such as changing an allowed directory, you can create or make the appropriate changes to that file and upload it to that server. You must 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 those in an Administrator role on the affected OpenDeploy server. See “Roles and Authorization” on page 117 for more information.

Any modified configuration file you upload must have the same file name as the one to replace. Names of the configuration files currently in use by the selected OpenDeploy server display 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 cannot 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.

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 have to map a drive to the selected host or to find another method to copy the file from the selected server to your local host.

To upload a modified configuration file to a remote OpenDeploy server

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


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

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

Figure 18 Upload a configuration file to a remote OpenDeploy server

5. Select the Overwrite box. This action is required any time you overwrite an existing configuration file.

6. Click Upload to copy the file from your computer to the selected OpenDeploy server. Your file is copied to the od-home/(od-instance)/etc directory and overwrites the existing file.

NOTE

The OpenDeploy server receiving your uploaded file cannot run with the changes in the updated configuration file until you refresh the server. See “Refresh the OpenDeploy Server” on page 80 for more information.

View 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 convenient way to see the configuration of a selected OpenDeploy server. Only valid XML files appear. Any other file produces an error message,


• • • •••


80

even if it appears in the View File list. This feature is only available to an Administrator role on the selected OpenDeploy server. See “Roles and Authorization” on page 117 for more information.

To view the source code of an OpenDeploy server configuration file


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 appears in the Configuration window (see Figure 19) immediately following the list.

Figure 19 View File List and Configuration window

If a file you want to view is not 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.

Refresh the OpenDeploy Server

Any changes you make to the configuration files in use are only effective 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 modifications to 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 appear in the Server Management window (see Figure 17 on page 76) under In-use Config Files.

The refresh feature in the Server Management window works the same as the iwodcmd serverreset command-line tool. See “Refresh the OpenDeploy Server” on page 66 for more information, including a list of 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 can only be used after refreshing the server. Any configuration change you make only apply to actions that occur after the server is refreshed. OpenDeploy cannot 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. You can only change the configuration files by modifying the service configuration file (deploy.cfg) and restarting the OpenDeploy services or daemons. See “Modify the Service Configuration File” on page 131 for 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. You can check these logs to determine when the refresh procedure completes before resuming OpenDeploy tasks.

This feature is only available to Administrator roles on the affected OpenDeploy server. See “Roles and Authorization” on page 117 for more information.

To refresh a selected OpenDeploy server’s configuration files


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

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 configuration changes

view the updating and refreshing status of a selected server group


• • • •••


82

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

The configuration files you can update and apply are listed in “Upload Modified Server Configuration Files” on page 78.

Create a Server Group

You can create a server group from any number of the existing OpenDeploy servers managed in the browser-based user interface. To include an OpenDeploy server in a server group that 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

1. Select Servers > View Server Groups to display the OpenDeploy Server Groups dialog box (see Figure 20).

Figure 20 OpenDeploy Server Groups dialog box

2. Click New Server Group to display the New Server Group dialog box (see Figure 21).

Figure 21 New Server Group dialog box

3. In the New Server Group dialog box you can create a new server group for the OpenDeploy user interface. After giving the server group a unique name, you decide which servers you want to comprise the server group.


• • • •••


Server Group Name box: Type a unique name for the server group.

Included Servers list displays the servers that currently part of the server group. You can remove a server by selecting it from this list and clicking Remove.

New Servers to Add list displays the servers available in the user interface that are not currently part of the server group. You can add a server by selecting it from this list and clicking Add.

Repeat this step for each server you wan to add.

4. (Optional) To remove a server from the Included Nodes list, select it and click Remove.

5. Click Save. The changes appear in the Server Groups dialog box (see Figure 22).

Figure 22 OpenDeploy Server Groups dialog box

View Server Groups

To view the server groups

select Servers > View Server Groups to display the Server Groups dialog box (see Figure 23).

Figure 23 Server Groups dialog box

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


• • • •••


84

Server GroupsThe Server Groups dialog box displays all the current server groups. A server group is a collection of OpenDeploy servers. You can apply changes to a server group and have those changes affect all the servers in the group simultaneously. Here you can edit or delete the membership of existing server groups. You can also create a new server group.

Group column displays the name of the server group.

Servers list displays the logical name of the server.

Port column displays the port used for sending and receiving deployments.

Edit button: Click to modify the server group name or the servers comprising the group.

Delete button: Click to remove the server group from the user interface.

New Server Group button: Click to display the New Server Group dialog box, where you can add a new server group.

In the Edit Server Group dialog box, you can make changes to an existing OpenDeploy server group, including changing the name and the makeup of the servers within the group.

Server Group Name box: Modify the name for the server group. If you change the existing name and save the changes, a new server group is created with the name and servers you specified before saving. The existing server group remains listed in the user interface in its existing state.

Included Servers list displays the servers that are currently a part of the server group. You can remove a server by selecting it from this list and clicking Remove. Software is not deleted.

New Servers to Add list displays the servers available in the user interface that are not currently part of the server group. You can add a server by selecting it from this list and clicking Add.

Save button: Click to save the server group you configured.

Add or remove servers from the server group by selecting them and clicking Add or Remove as needed.

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


• • • •••

Server Groups

Edit a Server Group

To edit a server group

1. Select Servers > View Server Groups to display the OpenDeploy Server Groups dialog box (see Figure 23 on page 83).

2. Click the Edit button associated with the server group you want to modify. The Edit Server Group dialog box opens (see Figure 24).

Figure 24 Edit Server Group dialog box

Delete a Server Group

To delete a server group

1. Select Servers > View Server Groups to display the OpenDeploy Server Groups dialog box (see Figure 23 on page 83).

2. Click Delete associated with the server group listed that you want to delete. The OpenDeploy Server Groups dialog box automatically refreshes with the deleted server group no longer displayed.

Manage 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 must consider that you cannot have a server group that contains a mix of base server and receivers to perform this task when creating server groups.


• • • •••


86

Edit Configuration Files for Server Groups

This next section describes how to create and upload server configuration files to a server group.

Server configuration files intended for server groups can be created and edited in the same manner as those for a single server. 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 is in the nodes configuration file, where you may want to include a node entry to allow the sending server to send deployments to itself for the purpose of testing.

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

OpenDeploy substitutes the address value associated with the affected server in the browser-based user interface. This address can be an IP address or a resolvable host name. You can include a mix of both types in a server group. See “Add an OpenDeploy Server” on page 73 for more information on adding servers to the user interface.

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

mars: 114.342.23.20

saturn: saturn

venus: venus.mycompany.com

To update their base server configuration files, you need to include the $hostname parameter for the localNode element’s host attribute value in the file you upload: <localNode host="$hostname"/>

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

mars: <localNode host="114.342.23.20"/>

saturn: <localNode host="saturn"/>

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


• • • •••

Server Groups

Upload Modified Configuration Files to the Server Group

The procedure for uploading modified configuration files to a server group is similar to that for a single server. See “Upload Modified Server Configuration Files” on page 78 for a general discussion of how uploading modified configuration files remotely works. When you upload the files, they apply equally to all the servers in the server group.

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

To upload modified configuration files to a server group

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

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

Figure 25 Server Group Management window

In the Server Group Management window, you can simultaneously upload modified OpenDeploy server files to all the servers included in a server group.

Select a Server Group list: Select the server group on whose servers the uploaded configuration file is to apply.

Refresh Server Group button refreshes each server in the server group to apply the changes made in the uploaded server file.

Upload File box: Type the path to the server configuration file you want to upload to the selected server. Alternatively, you can click Browse to navigate to the file.


• • • •••


88

Upload button: Click to upload the selected server file configuration. The file you select is copied to the od-home/etc directory of the selected host.


3. From the Selected Server Group list, select the server group to apply the uploaded configuration file to.

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

Figure 26 Upload a configuration file to a server group

5. Select the Overwrite box. This action is required any time you overwrite an existing file. Checking this box overwrites the file on every server in the group.

6. Click Upload to copy the file from your host to the selected server group. Your file is copied to the od-home/(od-instance)/etc directory of each server, and overwrites the existing file, if present. The Server Group Status pane (see Figure 27) displays the upload status.

Figure 27 Server Group Status pane

The Server Group Status table lists the status of each server in the server group after clicking Refresh Server Group to refresh the servers and apply the changes in the uploaded server file.

Name column displays the name of the server.


• • • •••

Server Groups

Address column displays the resolvable host name or IP address of the server's host.

Port column displays the server's port number.

Status column displays the refreshing status of the associated server.

If you omit selecting the Overwrite check box (see step 5), any recipient servers that already have that file do not accept the new uploaded file, and the message Upload Failed appears 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 to complete before you can start another. Click Uploading/Refreshing Status to update the status of the upload.

The servers in the group receiving your uploaded file cannot run with the changes in the updated configuration file until you refresh the them. See “Refresh the Server Group” for more information.

Refresh the Server Group

Any changes you make to the configuration files for a server group in use are implemented only after you refresh the servers. The same rules apply to updating a server group’s configuration files as when updating a single OpenDeploy server. See “Refresh the OpenDeploy Server” on page 80 for more information.

To refresh a server group

1. Select Servers > Manage Server Groups to open the Server Group Management window (see Figure 25 on page 87).

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

3. Click Refresh Selected Server Group.

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

To view the server group update status

1. Select Servers > Manage Server Groups to open 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.


• • • •••


90

Reconnect to a Restarted OpenDeploy Server

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

Determine the OpenDeploy Server Version

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

To determine the OpenDeploy server version


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

iwodservergetversion

The -h option for the iwodservergetversion command-line tool displays help.

Display 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


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

iwodcmd [-odinst instName] serverstatus

Various options are associated with the iwodcmd serverstatus command-line tool. Here is a list of the options, along with the usage syntax:

iwodservergetversion -h


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

iwodcmd [-odinst instName] serverstatus -listpathreg


• • • •••

Compose Deployments

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

use a text or XML editor

use the Deployment Configuration Composer

Use a Text or XML Editor

Modifying deployment configuration files requires an understanding of XML syntax, and of the deployment configuration DTD. Avoid modifying deployment configuration file unless you have expertise in both. Refer to “Deployment Types” in the OpenDeploy Deployment Configuration Guide for more information on modifying deployment configuration files.

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

For OpenDeploy to use them, all new and modified deployment configuration files must reside in: od-home/(od-instance)/conf

You can also organize subdirectories within /conf. See “Organize Deployment Configurations” on page 96 for more information.



-q Omits displaying the number of active deployments.

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

[path1,associated-deployment-uuid]

[path2,associated-deployment-uuid]

-odinst instName Uses the OpenDeploy server instance instName.


• • • •••


92

Use the Deployment Configuration Composer

The Deployment Configuration Composer is a tool in the OpenDeploy user interface that lets you create and modify existing deployment configurations without having to edit the files with 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 “Introduction to OpenDeploy” and “Deployment Features” in the OpenDeploy Deployment Configuration Guide before you can create a complete deployment configuration. Refer to “Composing Deployments” in the OpenDeploy Deployment Configuration Guide for more information on using this tool.

View Deployment Configuration Source CodeYou can view the XML-based source code of a selected deployment configuration’s file within the OpenDeploy user interface (see Figure 28).

Figure 28 View Configuration window


• • • •••

View Deployment Configuration Source Code

Viewing the source code of a deployment configuration allows you to identify and troubleshoot a deployment configuration file issue. You can also use this feature to see which element and attribute values are present, however, you cannot edit a deployment configuration displayed in the Deployment Configuration window. Instead you must edit the deployment configuration with a text or XML editor or by using the Deployment Configuration Composer. See “Compose Deployments” on page 91 for more information.

To view the source code of a deployment configuration

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

Figure 29 Deployment Configuration window

2. From the Selected Server list, select the name of the OpenDeploy server that contains the deployments whose configuration information you want to view.

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 “Organize Deployment Configurations” on page 96 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 appears in the window.


• • • •••


94

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

Upload Deployment ConfigurationsThe required location for deployment configuration files is: od-home/(od-instance)/conf

Deployment configuration files you place in this location 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 dialog box (see Figure 30).

Figure 30 Upload Configuration dialog box

Upload Configuration Dialog BoxThe Upload Configuration dialog box allows you to import a deployment configuration residing anywhere accessible by your server into OpenDeploy. Uploaded deployment configurations reside in the od-home/conf directory.

Selected Server list: Select the name of the OpenDeploy server to receive the uploaded deployment configuration.

Deployment Group list: Select the group to which you want to upload the selected deployment.


• • • •••

Upload Configuration Dialog Box

File box: Type the path to the deployment configuration file you want to upload. You also can click Browse to navigate to the file.

Browse button: Click to navigate to the location of the deployment configuration file you want to upload.


Upload button: Click to upload the selected deployment configuration file.

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

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

To upload a deployment configuration

1. Select Configurations > Upload Configuration to display the Upload Configuration dialog box.

2. Select the name of the OpenDeploy server receiving the uploaded deployment configuration from the Selected Server list.

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 “Organize Deployment Configurations” on page 96 for more information on deployment groups.

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

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

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


• • • •••


96

Organize Deployment ConfigurationsYou 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 can make each groups’ deployments only accessible to those who have the need. Some users can run production deployments, but not those in the test group.

You can further segment access by creating subgroups 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.

Create 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 subgroups within your deployment groups, for example: od-home/conf/test/internal

od-home/conf/test/external

You create deployment groups using one of the following methods:

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

Include a group subdirectory before the deployment name when editing a deployment configuration in the Deployment Configuration Composer. Use the “/” character as the


• • • •••

Organize Deployment Configurations

separator. For example, if you edit the deployment configuration refresh, you can append the new deployment group asia to the deployment in the Name box (see Figure 31):

Figure 31 Append 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.

View Deployment Groups

To view deployment groups and the deployment configurations they contain

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

Figure 32 Deployment Configuration window


• • • •••


98

The Deployment Configuration window allows you to view the source XML code for a selected deployment configuration. The window indicates any syntax errors in the deployment configuration that may prevent it from running successfully. You can also launch the Deployment Configuration Composer from this window, where you can create a new deployment configuration or edit an existing one.

Selected Server list: Select the name of the OpenDeploy server the deployments whose XML configuration information you want to view.

Deployment Group list: Select the name of the deployment group containing the deployment you want to view.

Deployment list: Select the name of the deployment whose XML configuration information you want to view. This information is displayed in the Configuration window.

Edit button: Click to open the Deployment Configuration Composer, where you can edit the selected deployment configuration.

New button: Click to open the Deployment Configuration Composer, where you can create a new deployment configuration.

DataDeploy Wrapper box: Click to configure the deployment configuration as a wrapper for a DataDeploy configuration.

Configuration window displays the source XML code for the configuration you selected.

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 “/” (see Figure 33).

Figure 33 Deployment Group List when selecting deployment directly under /conf

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

Only the deployment configurations residing under the deployment group you selected display in the Deployment list.

Directory Permissions for Deployment Groups

On UNIX hosts, the deployment group directories created under the /conf directory need to have “read-write-execute” permissions allowed for the user that the OpenDeploy base server


• • • •••

Run a Deployment from the User Interface

process runs as. For example, a permission of 755 allows the deployment group subdirectory to be accessible and readable by all, but only full access to the OpenDeploy base server.

Assign Access Controls

You can assign access controls to specific groups to limit access to deployments associated with that group. For example, you can 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 120 for more information.

Run a Deployment from the User InterfaceThis section describes how start and cancel deployments using the browser-based user interface. Alternatively, see “Run Deployments from the Command Line” on page 113.

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.

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

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

Figure 34 Start a Deployment dialog box


• • • •••


10

To start a deployment using the OpenDeploy user interface

1. Select Deployments > Start Deployment to display the Start Deployment dialog box.

2. Select the OpenDeploy server you want to act as the source of the deployment from the Selected Server list. When you select a given 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) Type the instance name of the deployment in the Instance Name box. The use of instances is described later in this section.

6. (Optional) Type the name=value pair for the parameter substitution in the Name=Value box. If you add multiple name=value pairs, separate each with a comma (,). Refer to “Parameter Substitution” in the OpenDeploy Deployment Configuration Guide for more information on this feature.

7. Click Simulate Deployment to perform a simulated deployment before actually moving files to the target servers. Otherwise, go on the next step. See “Perform a Simulated Deployment” on page 102 for more information.

8. Click Start Deployment to start the deployment. The Deployment Started dialog box opens (see Figure 35), displaying information about the deployment you just started.

Figure 35 Deployment Started dialog box

0 OpenDeploy® Administration Guide

• • • •••

Deployment Started Window

Deployment Started WindowThe Deployment Started dialog box opens when a deployment runs. This read-only dialog box displays basic information about the deployment.

Name displays the name of the deployment.

ID displays the identification number assigned to the deployment.

Start Time displays the date and time that the deployment is scheduled to start.

Source Host displays the name of the server hosting the deployment.

Targets displays the name of each recipient server of the deployment.

View Details button: Click to display the View Deployments dialog box, where you can view additional information about the deployment.

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

Deployment Instance Names

You can append the deployment name with a name, number, or other identifying characters to create a unique instance of the deployment. This allows a deployment using the same configuration file to 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 run once, and a new run of the deployment cannot be started until the previous one finishes.

A common use of this feature is in situations where multiple users initiate 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 run.

You can specify an instance in the Instance Name box of the Start a Deployment dialog box. The value you specify 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 combine to form the complete instance name. For example: reports01 or

reportsMonthly


• • • •••


10

No delimiter character is included, although you can specify one as part of the instance name itself, such as a period (.) or underscore (_). This 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 the extended name in the browser-based user interface, logging, and anywhere else where the deployment is tracked or monitored.

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

Perform a Test Deployment

After you install and configure OpenDeploy, you should perform a test deployment to ensure that everything works correctly. The OpenDeploy software includes a test deployment configuration test.xml that deploys files from one location to another on your OpenDeploy server. The test configuration only uses default settings in the server configurations files, so no further configuration is required.

When run, the test deployment configuration moves all the files 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 “Run a Deployment from the User Interface” on page 99 for more information. If you successfully deploy the file to its designated target location, you are ready to perform a deployment to another target server.

Perform a Simulated Deployment

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


• • • •••


To perform a simulated deployment

1. Select Deployments > Start Deployment to open the Start Deployment dialog box.

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

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

4. Select from one of the Logging Level options for the simulated deployment. See “Run a Deployment from the User Interface” on page 99 for more information.

5. Click Simulate Deployment to begin the simulation. The Deployment Started dialog box opens.

6. Click View Details to open the View Deployments dialog box to view deployment information for the simulated deployment.

7. Click View Log to view logging information to view the list of files that would be included in an actual deployment.

8. After evaluating the simulated deployment, you can 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 “Perform a Simulated Deployment” on page 115 for more information.

Check File Integrity on Production Servers

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


• • • •••


10

Cancel Deployments in Progress

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

Initial Setup. All deployments take time to set up the deployment before files are actually compared or moved. A large deployment with many target servers takes longer to perform its initial setup than a small deployment with few targets. Any deployment can be canceled during its initial setup phase.

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, results in a brief compare phase. A large number of files, even if the total file size is smaller, results 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 completes the transfer of any file in progress, and then cease any further activity.

Precommit Phase. Only transactional deployments can be canceled before or during the precommit phase in addition to the other phases. The precommit phase is when OpenDeploy determines whether all the targets successfully received their deployments.

Cancel Deployments in the User Interface

The Details table in the Source Deployments dialog box contains the Cancel Deployment button (see Figure 36).

Figure 36 Details Table with Cancel Deployment button

-

The Cancel Deployment button is active when cancellation of a running deployment is permitted. If the deployment progressed past that time if it completed, the button is unavailable. 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 “Monitor Deployments” on page 106 for more information on the Details table.

A target server cannot cancel a deployment it is receiving.


• • • •••


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

Depending on the speed of the deployment phases and when you issue the cancellation order, it is possible for a deployment to complete. The time when a cancellation is possible may close before OpenDeploy can process the deployment cancellation order. In other cases, the cancellation window can close before the user interface can fully display the Details table with the Cancel Deployment button.

To cancel a deployment in progress sent by your server

1. Select Deployments > View Deployments after a deployment has started. The Source Deployments dialog box opens.

If you started the deployment manually, you can click View Details in the Deployment Started dialog box to display the Source Deployments dialog box 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 display in the Details table.

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

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

Alternatively, you can cancel a deployment in progress from the command prompt by invoking the iwodcmd deploycancel command-line tool. See “Cancel a Deployment in Progress” on page 116 for more information.


• • • •••


10

Monitor DeploymentsYou can view information about deployments being sent in the Source Deployments window (see Figure 37) and being 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 37 Source Deployments window

Source Deployments WindowThe Source Deployments window provides a complete view of all deployments being sent or received by the selected OpenDeploy server.

Selected Server list: Select the name of the OpenDeploy server whose deployment information you want to view.

View list: Select Sending to display the Source Deployments window. Select Receiving to display the Target Deployments window.

Active check box: Select to view deployments that are currently active.

Completed check box: Select to view deployments that successfully completed.

Scheduled check box: Select 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 typing the number in the Day(s) box.

Update button: Click to refresh the window information, reflecting the current viewing options.


• • • •••

Source Deployments Window

Name (ID) column displays the name and identification number of the deployment. If an instance name was specified when the deployment was run or scheduled, that instance name appends to the deployment name. Selecting a deployment name displays its details in the Details table.

Start column displays the date and time the deployment started.

Target column displays the name of each target host receiving the deployment.

Status (Quorum) column displays the current status of the deployment, such as whether it is running, pending, completed, or failed. If a quorum is specified in the deployment, that number displays in parentheses.

Elapsed column the elapsed time the deployment has been running.

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

View Log button: Click to display the Deployment Log window, where you can view log information about the deployment.

Details table

Cancel Deployment button (displays only if the selected deployment is running): Click to cancel the selected deployment. A cancelled deployment cannot be restarted and is considered to have failed for transactional purposes.

Refresh button: Click to update refresh the window contents.

Target Host column displays the name of the server receiving the deployment.

Next Deployment column displays the name of the deployment being run in the next tier if the deployment is a multitiered.

Progress column displays the status and activity taking place in 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.


To monitor the progress of your deployments

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

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


• • • •••


10

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

Sending: Select to open the Source Deployments window. Information on deployments initiated by the server appears here. See the following section for details on the contents of the Source Deployments window.

Receiving: Select to open the Target Deployments window. Information on deployments received by the server appears here. See the following section for details on the contents of the Target Deployments window.

View Options

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


Completed check box: Select to view deployments that completed. You can modify the number of deployments displayed. See “Completed Sent Deployments Limit” on page 110 and “Completed Received Deployments Limit” on page 112 for more information.

Pending check box (Source Deployments window only): Select 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 typing 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 about all deployments being sent or received by the selected server, depending on whether the Source and Target Deployments window open.

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 appends with that instance. For example, if you ran the deployment reports and specified the instance value 01, that deployment displays as reports01. On the target, 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.

Select a deployment name to display its details in the Details table.


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.



Details Table

Clicking the deployment name displays the Details table under the Deployments table (see Figure 38).

Figure 38 Source Deployments dialog box—Details table

The Details table displays information about the source server or target servers participating in the deployment you select. If the Source Deployments dialog box is open and you select a deployment with multiple target servers, each target server appears in the Details table.

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


• • • •••


11

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

Progress column displays the status and activity taking place in the deployment at that time.

Elapsed column displays the elapsed time of the deployment.


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 dialog box while the deployment is in progress, the Details table indicates the deployment is still in progress, and under certain circumstances gives you the option of cancelling the deployment. See “Cancel Deployments in Progress” on page 104 for more information.


The Source Deployments dialog box (see Figure 37 on page 106) opens when you select Sending from the View list. The Source Deployments dialog box contains information about deployments originating from the selected OpenDeploy server that appear in the Deployments table.

The deployment name and its ID appear 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 ran or was scheduled, the deployment name appends the instance value. See “Deployments Table” on page 108 for a description of the Deployments table contents.

Completed Sent Deployments Limit

By default, the Source Deployments dialog box 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. See “Specify the Completed Deployments List” on page 197 for more information.


• • • •••

Target Deployments Window

Target Deployments WindowThe Target Deployments dialog box (see Figure 39) opens when you select Receiving from the View list.

Figure 39 Target Deployments dialog box

The Target Deployments dialog box provides a complete view of all deployments being received by the selected OpenDeploy server.

Selected Server list: Select the name of the OpenDeploy server whose deployment information you want to view.

View list: Select to Receiving display the Target Deployments dialog box. Select Sending to display the Source Deployments dialog box.


Completed check box: Select to view deployments that have been successfully completed.

Update button: Select to refresh the information, reflecting the current viewing options.

Name (ID) column displays the name and identification number of the deployment. If an instance name was specified when the deployment was run or scheduled, the instance name appends to the deployment name. Selecting a deployment name displays its details in the Details table.


Source column displays the name of the source host sending the deployment.

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


• • • •••


11




Details Table Refresh button: Click to update the window contents.

Source Host column displays the name of the server receiving the deployment.

Progress column displays the status and activity taking place with the deployment at that given time.



Cancel Deployment button (displayed only if selected deployment is running): Click to cancel the selected deployment currently running. A cancelled deployment cannot be restarted, and is be considered to have failed for transactional purposes.


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

Completed Received Deployments Limit

By default, the Target Deployments dialog box displays the last 50 completed deployment jobs (when the Completed option is selected) that were received by the selected server. This number includes multiple instances of the same deployment configuration. You can adjust that number in the server’s base server or receiver configuration file. See “Specify the Completed Deployments List” on page 197 for more information.


• • • •••

Run Deployments from the Command Line

Deployment Logs

Click View Log for either a deployment listed in the Source Deployment dialog box or one of the deployment’s corresponding source or target server lists in the Details table displays various types of logging information. See “Logs” on page 233 for more information.

Run Deployments from the Command LineCommand-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. Here is a list of the options with the usage syntax:

iwodcmd [-odinst instName] start -h | -v

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



deployment Name of the deployment to start.

-async Runs iwodstart command asynchronously. The iwodstart command returns before the deployment completes. See “Run Deployments Asynchronously” on page 116 for more information.

-inst instance Includes the deployment instance name instance, which is a suffix appended to the deployment name. This option is used to create unique deployment names for each instance of a deployment configuration.

-k "key=value" Specifies the key/value substitution. Refer to “Parameter Substitution” in the OpenDeploy Deployment Configuration Guide for more information.

Note that the parameter iwdd is reserved when you perform a deployment of a DataDeploy configuration. You may not use other parameter variables of the name iwdd.

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


• • • •••


11

The iwodcmd start command returns the following codes about the deployment status:

0: succeeded

1: failed to start

2: ran and returned a failed status

9: completed with errors

Authorization Checks

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

You can disable the default authorization checking through the service configuration file (deploy.cfg). See “Disable Authorization Check for Deployments Invoked with iwodcmd start” on page 134 for more information.

Start a Deployment

To start a deployment from the command line


2. Start the deployment by typing 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, to run the deployment reports, type the following command at the prompt:

iwodcmd start reports

-V arg Logging level with verbose or normal as arguments. See “Define Log Levels from the Command Line” on page 246 for more information.



• • • •••

Run Deployments from the Command Line

Perform a Simulated Deployment

See “Perform a Simulated Deployment” on page 102 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, to run the deployment reports as a simulated deployment, type the following command at the prompt: iwodcmd [-odinst instName] start reports -sim

Specify a Deployment Instance

Deployments are appended using the iwodcmd start command with the -inst instance using the following syntax: iwodcmd [-odinst instName] start deployment -inst instance

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

iwodcmd start reports -inst Monthly

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

reports01 or reportsMonthly

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

iwodcmd start reports -inst .monthly

This delimiter character appears in the complete instance name:

reports_01 or reports.monthly

See “Deployment Instance Names” on page 101 for more information on this feature.


• • • •••


11

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. Refer to “Parameter Substitution” in the OpenDeploy Deployment Configuration Guide 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 “Schedule Deployment Instances” on page 227 for more information on this usage.

Run Deployments Asynchronously

In some situations, you may want to start a deployment but not wait for the deployment to end before moving 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 runs asynchronously, only the deployment’s success or failure to start returns. 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, to run the deployment reports asynchronously, the command is: 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 waits for completion of the deployment before returning.

Cancel a Deployment in Progress

You can cancel a deployment in progress from the command line using the iwodcmd deploycancel command-line tool. Here is a list of the command options with the usage syntax:

iwodcmd [-odinst instName] deploycancel -h | -v

iwodcmd [-odinst instName] deploycancel deployment


• • • •••

Roles and Authorization

To cancel a deployment in progress from the command line


2. Cancel the deployment by typing 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, to cancel the deployment reports, type the following command at the prompt: iwodcmd deploycancel reports

The deployment is stopped without 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 “Cancel Deployments in Progress” on page 104 for more information.

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

Administrator allows full access to OpenDeploy configuration and functionality.

User authorizes an individual to perform deployment operations on specific deployments. A user role is created by an Administrator.

The role an individual has determines which 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:

scheduling, starting, and cancelling all deployments



deployment Name of the deployment to cancel.



• • • •••


11

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

viewing the OpenDeploy server log

viewing and uploading OpenDeploy server configuration files

creating deployment configurations

adding additional individuals to Administrator and User roles

designating which individuals with User roles can invoke given deployments

generating and accessing reports

configuring DAS

User Role

The User role authorizes an individual to perform deployment operations on specific deployments. Specifically, the User role can perform the tasks for their assigned deployments that include:

scheduling, starting, and cancelling deployments

viewing the schedules for the deployments

monitoring status

viewing the XML source code of a deployment configuration

viewing 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 the mars Web server at the operating system level. User1 is authorized to manage the deployments for the Residential Mortgage Web program, 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 role is allowed to launch only the deployment assigned to it.


• • • •••

Server Access Window

Server Access

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

Figure 40 Server Access window

Server Access WindowThe Server Access window allows you to add or remove OpenDeploy Administration (od-admin) and User (od-user) roles to users on a specific OpenDeploy host. Those with User roles assigned can subsequently have specific deployment configuration access assigned to them. The user must have a valid login name to have a role assigned.

Selected Host list: Select the name of the OpenDeploy server to which you want to assign access.

Domain list (Windows only): Select the domain for the OpenDeploy user you are adding.

Username box: Type the login name for the user.

Lookup User button: Click to display the roles currently held by the user.

Authorized Roles list displays the roles currently held by the user. You can remove an authorized user by selecting it from this list and clicking Remove.

Available Roles list displays roles available, but not currently held, by the user. You can add a role to a user by selecting it from this list and clicking Add.


• • • •••


12

Assign or Revoke Server RolesTo assign or revoke server roles

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

2. Select the OpenDeploy server to which to assign roles from the Selected Server list.

3. Type the individual’s user name in the Username text 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 appears 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.

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 no longer has 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 AccessIndividuals with Administrator access (od-admin) to an OpenDeploy server have unlimited access to that server’s deployments and deployment groups. See “Organize Deployment Configurations” on page 96 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 access on that server, and those individuals can have any number of deployments and deployment groups assigned them.


• • • •••

Deployment Authorization Window

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 (see Figure 41).

Figure 41 Deployment Authorization window

Deployment Authorization WindowThe Deployment Authorization window allows you to assign or remove the ability for specific individuals having a User role on that OpenDeploy server to perform and modify specific deployment configurations.

Selected Server list: Select the OpenDeploy server whose user roles you want to modify.

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

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

Deployment Group list: 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 “/”.

Authorized Deployments list displays the deployments for which the user is authorized. You can remove a deployment user by selecting it from this list and clicking Remove.

Deployment list displays the deployments the user is not currently authorized to use, but are available. You can add a deployment to a user by selecting it from this list and clicking Add.


• • • •••


12

To authorize User roles to perform specified deployments on a OpenDeploy server

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 119 for more information.

2. Select User Access > Deployments to display the Deployment Authorization window (see Figure 41 on page 121).

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.

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 does not appear. The user must have the od-user role assigned to appear in this list.

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

6. The deployment configurations and any subgroups contained in the deployment group you select are displayed in the Deployment box (see Figure 42).

Figure 42 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 (see Figure 43).

Figure 43 Authorized Deployments box

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

Authorize 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 unauthorize 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 OpenDeploy Administrator 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:


• • • •••


12

User file list: a text file that contains 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 that contains 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

The deployment names should not include the .xml extension.

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

iwodauthorize -h | -v

iwodauthorize -r list od-role [-odinst instName]

iwodauthorize -r (add | remove) od-role username ... [-odinst instName]

iwodauthorize -d list od-user [-odinst instName]

iwodauthorize -d (add | remove) od-user deployment-name...[-odinst instName]

iwodauthorize -d (add | remove | set) -ul user-filelist -dl deployment-filelist [-odinst instName] od-user




• • • •••


-ul user-filelist Specifies the path to the user file list for batch authorization. Each user entry must be on a separate line, 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

-dl deployment-filelist Specifies the path to the deployment file list for batch authorization. Each deployment group or individual configuration name must be on a separate line, for example: deployment1

deployment2

depgroup1/

-r list Lists users in a specified OpenDeploy role.

-r add Adds users to a specified OpenDeploy role.

-r remove Removes users from a specified OpenDeploy role.

od-role Specifies one of the following OpenDeploy roles:• od-admin

• od-user

username Specifies the name of the user.

od-user Specifies the name of a user with the od-user role.

-d list Lists deployment authorizations for the od-user role.

-d add Adds deployment authorizations to the od-user role. These are added to any existing authorizations already present.

-d remove Removes deployment authorizations from the od-user role. Only those deployment groups and configurations in the list are removed. Any previous authorizations are retained.


• • • •••


12

Add a Deployment Authorization

To authorize the set of users to run deployments listed in deployments.txt

type the following command: iwodauthorize -u /work/users.txt -d /work/deployments.txt -a add

The authorizations granted by this command are in addition to any previous authorizations the users already have.

Remove a Deployment Authorization

To unauthorize this same set of deployments from the same set of users

type the following command: iwodauthorize -u /work/users.txt -d /work/deployments.txt -a remove

This command does not remove any previous authorizations.

Reset All Deployment Authorizations

To reset the user list to include only the deployments in the deployment file

(any previous deployments are unauthorized)

type the following command: iwodauthorize -u /work/users.txt -d /work/deployments.txt -a set

To remove all authorizations without adding new ones

use the iwodauthorize command (with parameters as shown in the previous procedure) with reference to a deployment file list that does not contain entries.

-d set Resets the deployment authorizations for the od-user role with only those deployment groups and configurations in the deployment list. Any previous authorizations are lost. You can remove all deployment authorizations by specifying an empty file for the deployment-filelist value.



• • • •••


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.


• • • •••


12
• • • •••

Chapter 3

Server and Host Configuration

This chapter describes the initial server and host configurations you need to perform after installing the OpenDeploy software. These configurations can also apply to any subsequent instances of OpenDeploy you create. You can use this information to update and modify your OpenDeploy server configurations at later dates to reflect changes in your enterprise requirements.

The base server and receiver configuration files (by default odbase.xml and odrcvr.xml) are described in “Server Configuration Files” on page 175.

Access Service ManagementAll clients that use the OpenDeploy API interfaces to get access to the OpenDeploy server need to pass CSContextString for authentication. CSContextString can be obtained by using the ContentServices Foundation (CSF) Access service or by using CSSDK.

Access Service Management with CSF

The OpenDeploy administration server is configured to use a specific ContentServices Foundation (CSF) access service for authenticating users at login time. The CSF access service includes a key file (named passphrase by default) that is used to encode authenticated user session information. This key file resides in: csf-home/AccessService/etc

Copy the key file from its location in the CSF access service to the following location in each OpenDeploy server: od-home/(od-instance)/etc

You can give the key file a name other than the default passphrase, however, you must not change the content of the key file. If you do use a non-default name, that name must be updated in the OpenDeploy server’s service configuration file (deploy.cfg). See “Specify the Access


• • • •••

Chapter 3: Server and Host Configuration

13

Service Key File Usage and Name” on page 133 for more information. Refer to the ContentServices Foundation documentation for more information on the key file.

Access Service Management with TeamSite

The OpenDeploy administration server can also be configured to authenticate OpenDeploy users using CSSDK. The CSSDK includes a key file (named passphrase by default) that is used to encode authenticated user session information. This key file resides in the following location: TS-Home/Private/etc

To have the OpenDeploy server to use the CSSDK key file

copy the CSSDK key file into the OpenDeploy server instance from its location in the TeamSite to the following location in each OpenDeploy server:od-home/(od-instance)/etc

The following example is RMI-based that programatically explains how to create IWUser object from CSSDK CSClient that is used for invoking OpenDeploy Server functions://cssdk client which can be obtained from any of the cssdk CSFactory’s available

//Refer to CSSDK documentation of how to obtain CSClient

//CSClient csClient;

//Once CSClient is created

CSContext csContext = csClient.getContext();

String sessionString = csContext.getSessionString(); //CSSDK sessionstring

String userName = csClient.getCurrentUser().getName();

//create OD user

IWUser iwUser = new IWUser(userName, IWSecure.OD_ADMIN, OpenDeployAgent.ADMVERSIONOBJ, true);

iwUser.setClntApp(IWUser.APP_ADMINCONSOLE);

iwUser.setWebSvcIntVersion(null);

iwUser.setCSContextString(sessionString);

After setting sessionString in IWUser, iwUser can perform OpenDeploy tasks provided passphrase file is same in <TS-HOME>\private\etc and <od-home>\etc and iwUser has OD role.

Web Services Clients

Similar to the OpenDeploy administration server, Web Services clients must also authenticate users through the CSF access service or CSSDK. In addition, Web services clients are always required to have its user be decoded by the OpenDeploy server using the passphrase file. Therefore, be sure to copy the key file from the access service or TeamSite to


• • • •••

Modify the Service Configuration File

od-home/od_instance/etc as described in the previous section for each OpenDeploy base server and receiver whose Web services are accessed by client programs.

The following example is a WebService in C# which authenticates clients using CSSDK://cssdk client which can be obtained from any of the cssdk CSFactory’s available

//Refer to CSSDK documentation of how to obtain CSClient

//CSClient csClient;

//Once CSClient is created

CSContext csContext = csClient.getContext();

String sessionString = csContext.getSessionString();

//CSSDK sessionstring

//Create new OpenDeploy Context from CSSDK context.

od.wsclient.CSContext odContext = new od.wsclient.CSContext();

odContext.locale = "en_US";

odContext.appContext = "APP_ODWEBSVC";

odContext.serverName = "wire";

odContext.sessionString = sessionString ;

//handle of OD webservice

od.wsclient.OpenDeployService odservice = new od.wsclient.OpenDeployService();

//query for OD server status

CSODServerStatus status = odservice.getODServerStatus( odContext);

Modify the Service Configuration FileThe file deploy.cfg is the service configuration file for the base server and receiver. It contains service-related configuration information. Many of the attributes contained in this file are for modifying default values, such as the names of the configurations files and ports being used. Unlike other configuration files, you cannot change the name of this file from its default name.

The deploy.cfg file resides in the following location: od-home/(od-instance)/etc/deploy.cfg

The contents of service configuration file must be ASCII text, including any modifications you make. No multibyte or non-ASCII characters are allowed.

Specify the TeamSite Release

If you use OpenDeploy with TeamSite 6.7.x or later, no modification of the service configuration file is necessary.


• • • •••


13

If you use OpenDeploy with TeamSite 6.5.x or earlier, you must specify that release as the value for the teamsite.version attribute. Use the 6.x.x format when specifying the release. For example: teamsite.version: 6.5.0

Specify the Base Server and Receiver Configuration Files

The Deploy.serverConfig attribute’s value must point to the appropriate server configuration file depending on whether the server has base server or the receiver software installed. If you use the default configuration files for these types of servers, the attribute value is one of the following:

Base server: Deploy.serverConfig: odbase.xml

Receiver: Deploy.serverConfig: odrcvr.xml

If the server file has a different name than the default name listed here, the Deploy.serverConfig attribute’s value must point to that file. You also must ensure that the server configuration file being pointed to resides in the server’s od-home/(od-instance)/etc directory.

Specify the Nodes Configuration File

The Deploy.serverNodesConfig attribute’s value must point to the nodes configuration file for the server. If you point to the default nodes configuration file, the attribute is: Deploy.serverNodesConfig: odnodes.xml

If the nodes configuration file has a different name than the default files listed here, the Deploy.serverNodesConfig attribute’s value must point to that file. You also must ensure that the nodes configuration file being pointed to resides in the server’s od-home/(od-instance)/etc directory.

Specify the Bootstrap Administrator User Name

The Deploy.bootStrapUserName attribute allows you to define your own bootstrap administrator. The bootstrap administrator is a user account that can access the browser-based user interface (through the administration server) immediately after installation. This is an


• • • •••


optional feature. See “Configure the Bootstrap Administrator” on page 136 for more information. The format is:

Windows: Deploy.bootStrapUserName: domain-name\\username

NOTE

Note that two backslashes (“\\”) are required to separate the domain and the user name.

UNIX: Deploy.bootStrapUserName: username

Disable the Default Bootstrap Administrator Users

The Deploy.allowDefaultBootStrapUser attribute can be set to disable the default bootstrap administrator for an OpenDeploy base server or receiver. If you assign this attribute a value of no: Deploy.allowDefaultBootStrapUser: no

then only users you specified as bootstrap administrators, either during the base server or receiver installation, or by modifying the Deploy.bootStrapUserName attribute, can be used.

This is an optional feature with a default value of yes. The Deploy.allowDefaultBootStrapUser attribute is initially commented out in the service configuration file (deploy.cfg). You must uncomment it to change its value.

See “Default Bootstrap Administrator Users” on page 137 for more information on the default bootstrap administrator, including how to prevent it.

Specify the Access Service Key File Usage and Name

As an option, you can configure your OpenDeploy server to use the ContentServices Foundation (CSF) access service key file to ensure a user requesting an action through the browser-based user interface was authenticated by a specific CSF access service. If you want to use this key file, you must enable it in the Deploy.useAccessKeyFileForAdmin attribute. Specify the value y to enable the usage of the key file, for example: Deploy.useAccessKeyFileForAdmin: y

The default value is n (key file access is disabled).

If the access service key file authentication is enabled for the browser-based user interface, or if you are using OpenDeploy Web services, the Deploy.accessKeyFile attribute must point to the


• • • •••


13

access service key file that was copied from the appropriate ContentServices Foundation access service. If you are pointing to the default key file, the attribute is:

Deploy.accessKeyFile: passphrase

If the ContentServices Foundation access service key file has a different name than the default name passphrase, the Deploy.accessKeyFile attribute’s value must point to that file. The access service key file being pointed to must reside in the OpenDeploy server’s od-home/(od-instance)/etc directory, and its contents must match the contents of the corresponding key file under the CSF access service. Note that if the key file is not configured, but authentication is enabled for the user interface or you use OpenDeploy Web services, attempts to access the OpenDeploy server are denied.

The access key file is used for authentication by both the Web services clients and by the OpenDeploy administration server. Be aware of these dependencies if you change the Deploy.accessKeyFile attribute value.

Disable Authorization Check for Deployments Invoked with iwodcmd start

By default, authorization checking is performed when attempting to run a deployment using the iwodcmd start command-line tool. You can disable this authorization checking feature in the Deploy.cltProxyAuthCheck attribute. Specify the value n to disable authorization checking, for example: Deploy.cltProxyAuthCheck: n

See “Roles and Authorization” on page 117 for more information.

Configure RMI Ports for Administration through a Firewall

OpenDeploy lets you configure which RMI connection ports it uses so that you can administer the base server and receiver software using the browser-based user interface through your enterprise’s firewall. OpenDeploy uses 15 RMI connection ports in addition to the RMI Registry port that you provided during installation. Here the default port numbers are specified:

Server administration RMI connection ports: Deploy.rmiConnectionPort1: 24071

Deploy.rmiConnectionPort2: 24071






• • • •••



Event reporting RMI connection ports: Deploy.rmiConnectionPort7: 24078








As an option, you can configure each of these additional connection ports by specifying a unique valid number for each port with a text editor. You can modify any number and combination of these ports. These entries are initially commented out using the “#” symbol. Each entry can be activated by removing the #.

The valid port range is 1–65535, however, ports 1–1024 are reserved by the host’s operating system and normally should not be used. If a non-integer value (such as “xyz” or “1.5”) or a port number outside of the valid range is specified, OpenDeploy reverts to the default port number for that port. If a duplicate port number is specified, OpenDeploy reverts the values of all ports to their default values.

You can only configure these port numbers by opening the service configuration file and changing the number manually. The installation program does not prompt you for these numbers. You must restart the server’s base server or receiver services or daemons for any port changes you make to go into effect.

See “Deploy through a Firewall” on page 161 for more information on deploying files through a firewall.

Update Port Entries from a Previous Release

If you update your OpenDeploy base server or receiver software from a previous release, the installer does not update your service configuration file with the port entries, however, you can find them in the following sample file that is included with the software update: od-home/etc/examples/deploy.cfg_example

You can copy these settings from the sample file into your service configuration file using a text editor, and modify the port numbers as needed.


• • • •••


13

Specify the RMI Server Host Name or Binding IP Address

The Deploy.rmiServerBind attribute allows you to specify a host name or IP address for OpenDeploy to use in setting up its RMI services: Deploy.rmiServerBind: mars or

Deploy.rmiServerBind: 10.234.567.890

The RMI services are used to service the OpenDeploy administration server and to support event reporting. This property is useful when the host where the OpenDeploy base server or receiver is installed has multiple host names or IP addresses. It allows you to instruct the OpenDeploy base server or receiver which host name or IP address it should use to communicate to the OpenDeploy administration server.

Modifying the Deploy.rmiServerBind attribute is optional. If this entry is not specified, by default OpenDeploy uses the local host name.

The Deploy.rmiServerBind attribute is initially commented out with the “#” symbol. You must remove the # to implement any changes you make.

Ensure that the value you specify is correct. This value is passed to the Java RMI as a property. The result is unpredictable when the value is invalid.

Update Service Configuration File from a Previous Release

If you update your OpenDeploy base server or receiver software from a previous release, the installer does not update your service configuration file with the Deploy.rmiServerBind attribute, however, you can find it in the following sample file that is included with the software update: od-home/etc/examples/deploy.cfg_example

You can copy the Deploy.rmiServerBind attribute and its instructions from the sample file into your service configuration file using a text editor, and modify the attribute value as necessary.

Configure the Bootstrap AdministratorWhen you first log into OpenDeploy through the browser-based user interface (as managed by the administration server), you must do so as the bootstrap administrator. As the bootstrap administrator, you can start performing role access management by assigning OpenDeploy Administrator and User roles to the appropriate individuals who require access to each OpenDeploy base server and receiver through the administration server.


• • • •••

Configure the Bootstrap Administrator

The bootstrap administrator does not affect use of OpenDeploy outside the browser-based user interface, such as using command-line tools to schedule and run deployments.

Default Bootstrap Administrator Users

Each OpenDeploy base server or receiver has the following default bootstrap administrators automatically assigned to it:

Windows: host_name\Administrator

UNIX: root

You can also specify another bootstrap administrator user in addition to the default administrators. This user can be specified during installation. You can also add or change the bootstrap administrator user after installation. See “Modify the Bootstrap Administrator User” on page 138 for more information on adding a bootstrap administrator user after installation.

During installation, OpenDeploy automatically adds the default bootstrap users and any specified user to the od-admin role. If you do not specify a user, OpenDeploy only adds the default bootstrap administrators to the od-admin role.

Disable the Default Bootstrap Administrator Users

If you prefer the OpenDeploy base server or receiver not to allow the default bootstrap users, you can do so by updating the service configuration file (deploy.cfg) and specifying a value of no for the Deploy.allowDefaultBootStrapUser attribute: Deploy.allowDefaultBootStrapUser:no

This property is optional and has a default value of yes, which allows the use of the default bootstrap administrators. This property is initially commented out within the service configuration file. You must uncomment it to change the initial value. See “Modify the Service Configuration File” on page 131 for more information.

Setting this property to no on the OpenDeploy base server or receiver results in:

If this is the first time a fresh installation of OpenDeploy is started, the default bootstrap users are not added to the od-admin role.

If this is a subsequent OpenDeploy start, the default bootstrap users are removed from the od-admin role (if present).

If you start OpenDeploy at least once, and you then reset the Deploy.allowDefaultBootStrapUser attribute to yes, the default bootstrap users are not added back to the od-admin role. Instead, you must add the bootstrap user using the


• • • •••


13

Deploy.bootStrapUserName attribute in the service configuration file (deploy.cfg). For example: Deploy.bootStrapUserName: root

See “Specify the Bootstrap Administrator User Name” on page 132 for more information.

Modify the Bootstrap Administrator User

When you supply a bootstrap administrator user during the base server and receiver installation, that user account automatically is inserted in the base server or receiver’s service configuration file (deploy.cfg).

You have the option of adding your own bootstrap administrator user if none currently exists, or changing the existing one at any time by modifying the service configuration file and restarting the base server or receiver. The bootstrap administrator name must be a valid user account on the OpenDeploy server host. If the host platform is Windows, you must also supply the user’s domain.

Configuring the bootstrap administrator is the same for both Windows and UNIX. For upgrades, OpenDeploy uses the existing bootstrap information. You should check to see if the current values are still what you want.

To modify the bootstrap administrator on a OpenDeploy base server or receiver

1. Open the deploy.cfg file using a text editor. This file resides in: od-home/etc

2. Review the Deploy.bootStrapUserName attribute to ensure it has the bootstrap administrator name and domain (Windows only), and make any necessary modifications. For example:

Windows: WORKGROUP\\jdoe

UNIX: jdoe

NOTE

Note that two backslashes (\\) are required to separate the domain and the user name.

3. Restart the OpenDeploy base server or receiver service or daemon. See “Start OpenDeploy” on page 45 for more information.


• • • •••

Configure the Administration Server

Configure the Administration ServerThis section describes required configurations to the administration server required following installation.

Configure a Non-Default RMI Registry Port

To configure a non-default RMI registry port

1. If an OpenDeploy base server or receiver is installed on the same host as the administration server, and a non-default RMI registry port is used for the OpenDeploy server, you must modify the odservers.cfg file. This file resides in: admin-home/odadmin/config

2. Open the file using a text editor and update the node element’s port attribute value to reflect the non-default RMI registry port number you are using, for example:<node name="localhost" host="127.0.0.1" port="9173"/>

3. Save and close the odservers.cfg file. You must restart the administration server for the change to take effect.

RMI Ports for Legacy OpenDeploy Servers

This section applies to supported OpenDeploy 6.0.1 and earlier servers that are managed by the administration server.

The administration server software requires two different RMI ports to operate. These RMI ports are specified in the administration service configuration file (deployAdmin.cfg), which resides in: admin-home/odadmin/config

The default values for these ports are: DeployAdmin.rmiPort1: 25071

DeployAdmin.rmiPort2: 25072

To assign other RMI ports in place of these, you can edit the administration service configuration file and change the existing values using a text editor. These entries are initially commented out using the “#” symbol. Each entry can be activated by removing the #.

The valid port range is 0–65535 where 1–1024 are reserved ports by the operating system. Also, the value 0 can be used to allow the operating system to choose any available port at runtime. If a non-integer value (such as “xyz” or “1.5”) or a port number outside of the valid range is specified, OpenDeploy reverts to the default port number for that port. If a duplicate port number is specified, OpenDeploy reverts the values of all the ports to their default values.


• • • •••


14

You can only configure these port numbers by opening the service configuration file and changing the number manually. The installation program does not prompt you for these numbers. You must restart the administration service or daemon for any port changes you make to go into effect.

ContentServices Foundation Access Service

You must configure the administration server’s framework.properties file to use the CSF access service for login authentication. The administration server’s framework.properties file resides in: admin-home/httpd/iwwebapps/opendeploy/WEB-INF/conf

Open the framework.properties file using a text editor, and modify the following properties: DeployAdmin.ASHostname=access_service_hostname

DeployAdmin.ASPort=port_number

where access_service_hostname and port_number are parameters specified in the CSF access service websvc.cfg file. Refer to the ContentServices Foundation access service documentation for more information on the websvc.cfg file.

Configure HTTPS for the CSF Access Service

To configure admin server to communicate with CSF access service with HTTPS

1. Stop the OpenDeploy administration service or daemon. See “Stop OpenDeploy” on page 49 for more information.

2. Open the administration server’s framework.properties file using a text editor. This file resides in: admin-home/httpd/iwwebapps/opendeploy/WEB-INF/conf

3. Edit the following properties to have the correct values for the access service HTTPS transport:

DeployAdmin.ASHostname=access_service_host_name

DeployAdmin.ASPort=access_service_https_port_number

DeployAdmin.ASTransport=https

4. Locate the CSF access service that you want the OpenDeploy administration server to use, and export the associated certificate that the administration server requires into a file. Refer to the instruction in the README_AS_WEB_SERVICE file, which resides in: csf-home/websvc

for extracting the certificate from the CSF access service's serverkeys keystore file.

The next set of steps create the OpenDeploy odadminkeystore file using the certificate file from the CSF access service.


• • • •••


5. Copy the certificate file from the CSF access service to: admin-home/odadmin/config

This is the only location allowed for the certificate file.

6. Navigate to this directory and perform the following steps to add the certificate from the CSF access service into the odadminkeystore file. If this file does not exist, it is created when you run the subsequent command. Note that the file must be named odadminkeystore.

a. Type the following command at the prompt: admin-home/servletd/java1.4/jre/bin/keytool -import -v

-file certificate_file_name -keystore odadminkeystore

-storepass odadminkeystore_password -alias certificate_name

For example, to use certificate file asecrt.crt for the certificate named ascert, type: admin-home/servletd/java1.4/jre/bin/keytool -import -v

-file ascert.crt -keystore odadminkeystore -storepass ascertpwd

-alias ascert

b. Verify the certificate is in the odadminkeystore file by typing the following command at the prompt: admin-home/servletd/java1.4/jre/bin/keytool -list -v

-keystore odadminkeystore -storepass odadminkeystore_password

For example: admin-home/servletd/java1.4/jre/bin/keytool -list -v

-keystore odadminkeystore -storepass ascertpwd

7. Restart the OpenDeploy administration service or daemon. See “Start OpenDeploy” on page 45 for more information.

Configure HTTPS Browser Access for OpenDeploy

To configure administration server for browser access with HTTPS


2. Navigate to: admin-home/servletd/java1.4/bin

3. Run the keytool command by typing the following command at the prompt: keytool -genkey -alias tomcat -keyalg RSA

When the keytool asks for password, type: changeit

4. Open the server.xml file using a text or XML editor. This file resides in: admin-home/servletd/conf

5. Uncomment the Connector element located under the following heading: 


• • • •••


14

For example: <Connector className="org.apache.coyote.tomcat5.CoyoteConnector"

port="8443" minProcessors="5" maxProcessors="75"

enableLookups="true" disableUploadTimeout="true"

acceptCount="100" debug="0" scheme="https" secure="true"

clientAuth="false" sslProtocol="TLS"/>


You can test your connection by typing the following URL in the browser: https://admin-server-host:8443/iw/opendeploy

You can access additional information on the key generation and using third-party signed certificates from the following Web site: http://jakarta.apache.org/tomcat/tomcat-5.0-doc/ssl-howto.html

NOTE

This Web site can change at any time.

Change the Keystore Password

You can change the keystore password from its default value; it is necessary that both the generated certificate and the keystore share the same password.

New Installations

The following instructions are for new OpenDeploy installations, or if you use SSL encryption for the first time.

To change the keystore password for new installations



3. Generate a new keystore by typing the following command at the prompt: keytool -genkey -alias tomcat -keyalg RSA -keypass password

-keystore keystore_filepath -storepass password

where both passwords are the same value, and keystore_filepath is the absolute path of the keystore file.


• • • •••


4. Open the server.xml file using a text or XML editor. This file resides in: admin-home/servletd/conf

5. Uncomment the Connector element located under the following heading: 

6. Replace the existing Connector element and its attributes and child elements with the following updated Connector element: <Connector className="org.apache.coyote.tomcat5.CoyoteConnector"




clientAuth="false" sslProtocol="TLS"

keystoreFile="keystore_filepath"

keystorePass="password"/>

where keystore_filepath is the absolute path of the keystore file, and password is the password of the keystore and the certificate.

7. Save and close the server.xml file.


Existing Installations

The following instructions are for upgraded OpenDeploy installations where SSL encryption has already been configured and you already have an existing keystore.

To change the keystore password for existing installations



3. Locate the keystore file in the place you want.

4. Change the keystore password by running the following command from the prompt: keytool -storepasswd -keystore keystore_filepath

5. Change the key password by running the following command from the prompt: keytool -keypasswd -keypass changeit -new password -alias tomcat

-keystore keystore_filepath

6. Open the server.xml file using a text or XML editor. This file resides in the following location: admin-home/servletd/conf


• • • •••


14

7. Replace the existing Connector element and its attributes and child elements with the following updated Connector element: <Connector className="org.apache.coyote.tomcat5.CoyoteConnector"




clientAuth="false" sslProtocol="TLS"

keystoreFile="keystore_filepath"

keystorePass="password"/>

where keystore_filepath is the absolute path of the keystore file, and password is the password of the keystore and the certificate.

8. Save and close the server.xml file.


Specify an Alternate TeamSite Mount PointIf you plan to use DAS or run standalone database deployments from a TeamSite source file location, you must specify the location of the TeamSite mount point in the appropriate location.

Windows: Open the TeamSite /etc/iw.cfg configuration file. Add the following line to the [locations] section: iwmount=location-of-mount-point

UNIX: Open the /etc/defaultiwmount file. The first line of this file should be set to the mount point.

If your TeamSite mount point is not specified as described, the OpenDeploy administration file browser interface uses the following mount point:

Windows: Y:

UNIX: /iwmnt

Note that these values may not be correct. If you encounter problems with the file browser interface, verify that the mount point location has been properly specified.

Failure to specify the correct TeamSite mount point causes file browser interface to function improperly.


• • • •••

Enable Cross-Platform Administration

Enable Cross-Platform AdministrationThis section describes how to use the OpenDeploy browser-based user interface on one supported platform (Windows or a version of UNIX) to administer an OpenDeploy server residing on an opposite platform.

Often it is desirable or necessary to use the OpenDeploy browser-based user interface running on a Windows host to administer OpenDeploy base server and receiver software running on UNIX hosts. This requires the bootstrap administrator on each UNIX host to match the bootstrap administrator specified on the Windows host running the administration software. If this is not set up properly, you may see the following message when you try to access the server from the Manage Servers window: The request to view server configuration was denied.

When you install OpenDeploy on a UNIX host, the installer script prompts you for the type of host (Windows or UNIX) on which your base server or receiver server software runs. You should select the Windows option. Then, when you receive a prompt to provide your bootstrap administrator information, you provide the same user name and domain as you did for the Windows host running the administration server software.

If you did not perform this task during the OpenDeploy installation, you can type the correct user name and domain in the service configuration file (deploy.cfg) on the UNIX host. For example: Deploy.bootStrapUserName: my-windows-domain\\my-windows-username

After modifying the service configuration file, restart the OpenDeploy base server or receiver software. See “Modify the Service Configuration File” on page 131 for more information.

This same method applies for managing OpenDeploy base server and receiver software running on Windows hosts when the administration server software is running on a UNIX host. The bootstrap administrator user name must match that of the UNIX host’s service configuration file. For example: Deploy.bootStrapUserName: my-unix-username

After making modifications to the service configuration file, restart the OpenDeploy base server or receiver software.

Define Target NodesWhen the base server or receiver component is installed on your OpenDeploy base server, it includes the nodes configuration file. The nodes configuration file contains lists and information


• • • •••


14

for each OpenDeploy instance within the OpenDeploy environment capable of receiving files from the sender, including:

logical name

physical host name

listener port of the given OpenDeploy instance

When the base server software is installed, the nodes configuration file is created with a single node list for the initial OpenDeploy instance on the host. This allows you to configure the OpenDeploy base server to deploy files to itself, however, you must add all other target nodes into the nodes configuration file manually. Any target node you add must have the base server or receiver software installed on it.

The name and location of the default nodes configuration file that is installed with the OpenDeploy base server software is: od-home/(od-instance)/etc/odnodes.xml

This file can be renamed, however, that name must be referenced in the OpenDeploy server’s service configuration file (deploy.cfg) as the value of the Deploy.serverNodesConfig attribute. See “Modify the Service Configuration File” on page 131 for more information.

Encoding

The nodes configuration file can be encoding other than UTF-8. For example, if a value in the file contains Japanese characters, the encoding needs to be: <? xml version="1.0" encoding="SHIFT_JIS" ?>

For French and German, the encoding value is: <? xml version="1.0" encoding="ISO-8859-1" ?>

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

Physical Host Names

When a physical host name is required for an OpenDeploy server host, you typically can provide one of the following options:

host name: for example mars

fully-qualified DNS host name: for example mars.mycompany.com

IP address: for example 114.342.23.21


• • • •••

Define Target Nodes

When you use either the host or fully-qualified DNS host names, it must be unique in the OpenDeploy environment, and resolvable to the IP address of the host.

Logical Server Names

OpenDeploy allows you to map a simple logical name to the pairing of the OpenDeploy server instance hosts’s physical name and the instance’s deployment port number. You can use any logical name you want, as long as it is unique to that pairing.

Using a brief logical name relieves you from having to type lengthy host names into each deployment configuration. Additionally, in many organizations the deployment group is separate and distinct from the network group. Administratively, if there are changes in the network, such as a server being replaced, it does not affect the deployment configuration, just the nodes configuration file where the mapping of names occurs.

Specify Server Nodes

The nodes configuration file contains the nodeSet element, which houses the individual server nodes lists. You can provide an ID value for the name attribute of the nodeSet element, for example: name="od_receiver_nodes"

or keep the default implied name.

Within this element you can add a separate instance of the node element for each server within the OpenDeploy environment. The node element has the following attributes:

name: the logical name of the server node as it appears in OpenDeploy configuration files. For example: name="venus"

host: the resolvable host name or the IP address of the server. For example:

host="venus.mycompany.com" or host="114.342.23.21"

port: the listening port number used by the OpenDeploy server to send and receive deployed files. For example: port="20014"

The port number should match the value for the listenerProperties element’s bindPort attribute value in the base server configuration file. This value is typically the deployment port number you typed during installation of the base server software.


• • • •••


14

In the next example, if you have the following nodes in the OpenDeploy environment:

venus.mycompany.com (IP address: 114.342.23.21)

jupiter.mycompany.com (IP address: 114.342.23.22)

saturn.mycompany.com (IP address: 114.342.23.23)

and you want to create and use logical names for them, you can map their logical names to their host names and deployment ports this way: <nodeSet name="od_receiver_nodes">

<node name="venus" host="venus.mycompany.com" port="20014"/>

<node name="jupiter" host="jupiter.mycompany.com" port="20014"/>

<node name="saturn" host="saturn.mycompany.com" port="20014"/>

</nodeSet>

You can also map logical names to their IP addresses in this way: <nodeSet name="od_receiver_nodes">

<node name="venus" host="114.342.23.21" port="20014"/>

<node name="jupiter" host="114.342.23.22" port="20014"/>

<node name="saturn" host="114.342.23.23" port="20014"/>

</nodeSet>

You can even mix host names and IP addresses: <nodeSet name="od_receiver_nodes">



<node name="saturn" host="114.342.23.23" port="20014"/>

</nodeSet>

See “Logical Server Names” on page 147 for more information on the use of logical names.

Multiple Instances

You can deploy to multiple instances of OpenDeploy residing on the same host. Each instance is treated as a separate target node, and must be configured individually in the nodes configuration file of the sender. Multiple instances of OpenDeploy on the same host share the same physical host, but must have different port numbers. Each instance’s logical name is based on the unique pairing of the physical host name and the individual instance’s deployment port.

In the following example, three separate OpenDeploy instances on the same host are configured in the nodes configuration file: <nodeSet name="od_receiver_nodes">

<node name="venus01" host="venus.mycompany.com" port="20014"/>




• • • •••

Define Target Nodes

</nodeSet>

See “Run Multiple Instances of OpenDeploy” on page 52 for more information on this feature.

Hosts with Multiple IP Addresses

If you have a node in your OpenDeploy environment with multiple IP addresses (with one or multiple network interface cards), you must specify an IP address rather than the host name for that node’s host attribute value.

Case Insensitivity of Logical Names Allowed

The logical names of servers listed in the nodes configuration file and servers listed as the nodeRef element’s useNode attribute value in a deployment configuration is case insensitive. For example, if you have the following entry in the nodes configuration file: <node name="venus" host="venus.mycompany.com" port="20014"/>

and you referenced this host in a deployment configuration as: <nodeRef useNode="Venus"/>

the target node can still be located and the deployment could take place.

Define Target Replication Farms

You can define target replication farms in the nodes configuration file 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 node is added, you can update the replication farm defined in the nodes configuration file, and all the deployment configurations that reference that replication farm are automatically updated. Otherwise, it would be necessary to update the replication farm defined in each individual deployment configuration.

Replication farms are defined in the nodes configuration file using the replicationFarmSet element: <nodeSet name="od_receiver_nodes">

...

<replicationFarmSet>

<replicationFarm name="my_replication_farm">


• • • •••


15

...

</replicationFarm>

</replicationFarmSet>

</nodeSet>

Within the replicationFarmSet element is a separate replicationFarm element for each farm you define. Within the replicationFarm element are individual nodeRef elements associated with each target node that you had previously defined in the nodes configuration file.

For example, to define the target replication farm my_replication_farm using the nodes defined earlier in this section, the nodes configuration file contains: <nodeSet name="od_receiver_nodes">



<node name="saturn" host="saturn.mycompany.com" port="20014"/>

<replicationFarmSet>

<replicationFarm name="my_replication_farm">

<nodeRef useNode="venus"/>

<nodeRef useNode="jupiter"/>

<nodeRef useNode="saturn"/>

</replicationFarm>

</replicationFarmSet>

</nodeSet>

Refer to “Target Replication Farm” in the OpenDeploy Deployment Configuration Guide for more information on how target replication farms are defined, and how to reference replication farms defined in the nodes configuration file from a deployment configuration.


• • • •••

Set up OpenDeploy in a Microsoft Cluster Environment


This section describes the preparation and setup for installing and using a single instance of OpenDeploy with SNMP disabled in a Microsoft Cluster environment.

Prerequisites

Before you can install OpenDeploy into a Microsoft Cluster environment, you must ensure that the following prerequisite tasks have been completed:

Each node that has OpenDeploy software installed has its own host name and IP address.

The Microsoft Cluster must have its own host name and IP address.

If you plan to use the OpenDeploy browser-based user interface to manage the OpenDeploy servers in the Microsoft Cluster, you must define a domain user that exists in all the OpenDeploy server nodes in the cluster. During OpenDeploy installation, enter this user as the bootstrap user.

License

Refer to “Licensing Cluster Hosts” in the OpenDeploy Installation Guide for information.

Installation

You must perform the next procedure on each OpenDeploy host in the Microsoft Cluster environment.

To install each OpenDeploy host in the Microsoft Cluster environment

1. Determine the path you want to install the OpenDeploy base server or receiver on each node. This path should be identical on all the nodes, ensuring each node’s OpenDeploy server configuration files are the same. The location cannot be on a shared disk array, as it can cause problems when applying service packs.

2. Install the appropriate OpenDeploy base server or receiver on each node. Refer to “Installation” in the OpenDeploy Installation Guide for installation information.


• • • •••


15

If you want to use the OpenDeploy browser-based user interface to manage your OpenDeploy servers, use the domain user described in the previous section as the bootstrap administrator, rather than the local user.

3. Restart the OpenDeploy software, either by manually starting each OpenDeploy service or daemon, or by restarting each OpenDeploy server node. See “Start OpenDeploy” on page 45 for more information.

4. Check the OpenDeploy server log (hostname_odbase.log or hostname_odrcvr.log) to ensure the OpenDeploy server software started correctly. These logs reside in the following location: od-home/log

You can also install the OpenDeploy administration package and the ContentServices Foundation access service on each node in the Microsoft Cluster environment. Follow the same steps to install the administration package as you did the OpenDeploy server software.

OpenDeploy Server Setup

After you install the OpenDeploy software, you must perform the next procedure on each OpenDeploy server on each node.

To set up OpenDeploy server on each node

1. Stop the OpenDeploy base server or receiver. See “Stop OpenDeploy” on page 49 for more information.

2. Open the OpenDeploy server configuration file (by default odbase.xml or odrcvr.xml) using a text or XML editor. These files reside in: od-home/etc

3. Substitute the Microsoft Cluster name for the local host name for the host attribute value in the localNode and node elements. For example:

<localNode host="MS_cluster"/> and

<allowedHosts>

<node host="MS_cluster"

...

</allowedHosts>

where MS_cluster is the name of the Microsoft Cluster.

4. (Base servers only) Open the nodes configuration file. This file resides in: od-home/etc

5. Substitute the Microsoft Cluster name for the local host name in the node element’s host attribute value. For example: <nodeSet>

<node ... host="MS_cluster" ..."/>


• • • •••


</nodeSet>

6. Open the OpenDeploy service configuration file (deploy.cfg) using a text editor. This file resides in: od-home/etc

7. Type the Microsoft Cluster name for the following attribute values:

Deploy.rmiServerBind: MS_cluster

Deploy.cltProxyAllowHost: MS_cluster, localhost


Configure OpenDeploy Web Service

The next procedure describes how to configure the OpenDeploy base server or receiver on each node in the Microsoft Cluster for OpenDeploy Web Service.

To configure OD base server or receiver on each node for OD Web service

1. Stop the OpenDeploy base server or receiver. See “Stop OpenDeploy” on page 49 for more information.

2. Open the OpenDeploy server configuration file (by default odbase.xml or odrcvr.xml) using a text editor. These files reside in: od-home/etc

3. Type the Microsoft Cluster name for the httpTransport host name and the httpsTransport host name:

<httpTransport ...host="MS_cluster"> or <httpsTransport ... host="MS_cluster">


Configure Event Reporting

The next procedure configures a OpenDeploy base server and receiver on each node in the Microsoft Cluster for event reporting.

To configure an OD base server and receiver on each node for event reporting

1. Open the event reporting configuration file (eventReportingConfig.xml). This file resides in the: od-home/etc

2. Substitute the Microsoft Cluster name for the local host name in the log element’s path attribute value. For example: <log path="od-home/log/MS_cluster_publisher.log" ... />


• • • •••


15

3. Substitute the Microsoft Cluster name for the local host name in the jndiContext element’s url attribute value. For example: <jndiContext url="rmi://MS_cluster:9173/JndiServer" ... >

4. Open the JMS configuration file (jmsConfig.xml).This file resides in: od-home/etc

5. Substitute the Microsoft Cluster name for the local host name in the ServerConfiguration element’s host attribute value. For example: <ServerConfiguration host="MS_cluster" ... />

6. Substitute the Microsoft Cluster name for the local host name in the RmiConfiguration element’s registryHost attribute value. For example: <RmiConfiguration ... registryHost="MS_cluster" ... />

See “Configure Event Reporting in the Microsoft Cluster” on page 157 for information on configuring event reporting in the administration server in a Microsoft Cluster environment.

Microsoft Cluster Setup

After you complete the OpenDeploy server setup tasks, you must perform the following Microsoft Cluster setup procedure on each node.

To set up Microsoft Cluster setup procedure on each node

1. Stop the OpenDeploy base server or receiver service. See“Stop OpenDeploy” on page 49 for more information.

2. Reconfigure the OpenDeploy base server or receiver service to start manually rather than automatically.

3. From the Microsoft Cluster’s primary node, open the Cluster Administration Window for the Microsoft Cluster that contains the OpenDeploy server node.

4. Select File > New > Resource in the Microsoft Cluster to create a new resource for the OpenDeploy server. The process for creating the new resource includes the following tasks:

a. Type the Name, for example OpenDeploy server.

b. For the Resource Type, select Generic Services.

c. For the Group, select Cluster Group.

d. Click Next. The Possible Owners window opens.

5. Select all the OpenDeploy server nodes in the Possible Owners window and click Next. The Dependencies window opens.

6. Select Cluster IP Address, Cluster Name, and all the shared drives to which the OpenDeploy server needs access in the Dependencies window, and click Next. The Generic Service Parameters window opens.


• • • •••


7. Type iwodserver for the service name and click Next. The Registry Replication window opens.

8. Click Finish in the Registry Replication window. The following message appears: "Cluster resource resource_name created successfully"

where resource_name is the name you gave the resource, such as OpenDeploy server. You also see the new resource you just created in the Cluster Administration window.

9. Have the Microsoft Cluster start the OpenDeploy server on the primary node by right-clicking on the OpenDeploy server resource and selecting Bring online from the shortcut menu.

10. Check the OpenDeploy server log to ensure the OpenDeploy server software started correctly. Note that the OpenDeploy server log name uses the node’s name and not the cluster’s name.

11. Force the Microsoft Cluster to simulate a failure on the primary node so it switches the primary to the other node.

a. Right-click the resource you created for OpenDeploy server and select Properties > Advanced from the shortcut menu.

b. Check Affect the group in the Restart window. Set the Threshold value to 0. This sets the threshold to 0, which means do zero retries on the existing node before switching to the other node.

c. Click OK.

d. Right-click the resource you created for the OpenDeploy server and select Initiate Failure from the shortcut menu. This stops OpenDeploy on the current node, then start OpenDeploy on the other node.

The Cluster Administration Window shows when the resource for the OpenDeploy server switches to the other node.

12. Check the OpenDeploy server log on the node that was started to make sure OpenDeploy came up successfully.

13. Change the threshold back to an appropriate level for your site.

During normal operation, all nodes should be running, but the OpenDeploy base server or receiver service should only be running on the active node.


• • • •••


15

Deploy into a Microsoft Cluster

You must perform the following procedure for any OpenDeploy base server that deploys content to an OpenDeploy server residing in a Microsoft Cluster.

To set up any OpenDeploy base server to deploy content to an OpenDeploy server

1. Open the sending OpenDeploy base server’s nodes configuration file using a text or XML editor.

2. Add a node element entry for the Microsoft Cluster. For example: <nodeSet>

...

<node name="cluster01" host="MS_cluster" port="20014"/>

</nodeSet>

3. Open the sending server’s deployment configuration file with a text or XML editor.

4. Modify the nodeRef element’s useNode attribute value to reference the Microsoft Cluster. For example: <nodeRef useNode="cluster01"/>

5. Update the base server or receiver configuration files for each OpenDeploy server in the Microsoft Cluster to allow the receiving of deployments from the sending OpenDeploy base server. See “Specify Allowed Hosts for Received Deployments” on page 190 for more information.

Deploy Content from a Microsoft Cluster

You must add the Microsoft Cluster to the allowed hosts list on any OpenDeploy base server or receiver that you want to receive deployed content from an OpenDeploy server in the Microsoft Cluster. Open the base server or receiver configuration file of the receiving OpenDeploy server and add the Microsoft Cluster to the allowed hosts list. For example: <allowedHosts>

...

<node host="cluster01">

...

</node>

...

<allowedHosts>


• • • •••


Administration Package Configuration

The next sections describe configuration requirements associated with using the administration package software in a Microsoft Cluster environment.

Add the Administration Server to the Microsoft Cluster

You can include the administration server in the Microsoft Cluster resource group you created for the OpenDeploy servers. The administration/reporting server name is iwodadmin. See “Microsoft Cluster Setup” on page 154 for more information. You must change your administration server’s startup type from automatic to manual.

Configure the CSF Access Service for the OpenDeploy Administration Server

The next procedure configures the OpenDeploy administration server on each node in the Microsoft Cluster for the ContentServices Foundation (CSF) access service.

To configure the CSF access service for the OpenDeploy administration server

1. Stop the OpenDeploy administration server. Se “Stop OpenDeploy” on page 49 for more information.

2. Open the administration server’s framework.properties file using a text editor. This file resides in: admin-home/httpd/iwwebapps/WEB-INF/conf

3. Type the Microsoft Cluster name for the DeployAdmin.ASHostname attribute value if the CSF access service OpenDeploy administration server uses resides on the Microsoft Cluster. For example: DeployAdmin.ASHostname=MS_cluster


Configure Event Reporting in the Microsoft Cluster

To include the Microsoft Cluster in event reporting

1. Open the odservers.xml using a text or XML editor. This file resides in: admin-home/odadmin/config

2. Substitute the Microsoft Cluster name for the local host name in the reportingConfiguration element’s hostName attribute. For example: <reportingConfiguration hostName="MS_cluster">


• • • •••


15

3. Substitute the Microsoft Cluster name for the local host name in the log element’s path attribute that corresponds to the OpenDeploy subscriber log. For example: <log name="openDeploySubscriberLog" path="admin-home/odadmin/log/

MS_cluster_subscriber.log" ... />

4. Substitute the Microsoft Cluster name for the local host name in the log element’s path attribute that corresponds to the OpenDeploy database log. For example: <log name="databaseLog" path="admin-home/odadmin/log/

MS_cluster_database.log" ... />

5. Substitute the Microsoft Cluster name for the local host name in the odNode element’s host attribute. For example: <odNode host="MS_cluster" ... />

Using event reporting in a Microsoft Cluster environment also requires configuration of the base server and receiver configuration files. See “Configure Event Reporting” on page 153 for more information.

Access the OpenDeploy Administration Server in a Microsoft Cluster

You can access the OpenDeploy administration server in a Microsoft Cluster from your browser using the following URL: http://MS_cluster:admin-port-number/iw/opendeploy/login

for example: http://cluster01:8081/iw/opendeploy/login

You can access a running OpenDeploy server in the Microsoft Cluster through the user interface by specifying the server name, similar to accessing standalone OpenDeploy servers.

CSF Access Service Package Configuration

You can include the CSF access service in the Microsoft Cluster resource group you created for the OpenDeploy servers. The CSF access service name is iwas. See “Microsoft Cluster Setup” on page 154 for more information.

You must change your Access Service startup type from automatic to manual.

To configure the CSF access service on each node in the Microsoft Cluster

1. Stop the CSF access service. Refer to the CSF access service for more information.


• • • •••

Configure the iwodcmd Command-Line Tool

2. Open the CSF access service’s websvc.cfg configuration file using a text editor. This file resides in: csf-home/AccessService/etc

3. Type the Microsoft Cluster name for the following attributes:

Websvc.HTTPHostName: MS_cluster

Websvc.HTTPSHostName: MS_cluster


4. Open the CSF access service’s websvclog4j.cfg logging configuration file using a text editor. This file resides in: csf-home/AccessService/etc

5. Type the Microsoft Cluster name for the following:

log4j.appender.eventLog.File=... /AccessService/log/MS_cluster_AS_events.log

log4j.appender.errorLog.File=... /AccessService/log/MS_cluster_AS_errors.log


Configure the iwodcmd Command-Line ToolThe iwodcmd command-line tool executes certain OpenDeploy actions, and represents a more efficient method of operation over previous, Java-based OpenDeploy commands. Refer to “iwodcmd” in the OpenDeploy Reference for more information on this tool.

Service Configuration File Settings

By default, you can run iwodcmd without additional configuration, using the default values, however, you can specify your own values in the service configuration file (deploy.cfg).

This file contains the following options for iwodcmd support:

Deploy.cltProxyPort: specify the port on which the OpenDeloy iwodcmd listener binds. The default port is 3434.

Deploy.cltProxyHost: specify the network address on which the OpenDeloy iwodcmd listener binds. The default address is localhost.

Deploy.cltProxyAllowedHost: specify the network address/host from which the OpenDeloy iwodcmd listener allows iwodcmd execution. The value can be a comma separated list of network addresses or host names. The default address is localhost.


• • • •••


16

Deploy.cltProxyEnable: specify whether (y or n) the OpenDeploy iwodcmd listener is enabled. The default setting is enabled (y).

If a specified value is missing or is invalid, OpenDeploy reverts to the default value for that option.

These configurations are not automatically added to your service configuration file during installation. You must open the service configuration file with a text editor and manually add the options and their corresponding values. You can copy and paste these options into your service configuration file from the example file residing in: od-home/etc/examples/deploy.cfg_example

When you copy and paste these options into your service configuration file, you must also uncomment them by removing the “#” in front of each line.

You must restart your base server or receiver software to enable any changes to these settings you make.

Specify Alternate Ports and Hosts

You can explicitly specify the port and host values to use on the iwodcmd command line with the -host and -port options. The following usage rules apply:

If both -host and -port are specified, the command connects to the base server or receiver on the specified host using the specified port. If you are using iwodcmd to connect to a remote OpenDeploy server host, you must specify both options.

If only -host is specified, the command connects to the specified host using the default port, 3434.

If only -port is specified, the command connects using the specified port to the network address/host configured in the service configuration file (deploy.cfg), under Deploy.clt.ProxyHost section.

If neither options is specified, the command uses the host and port specified in the service configuration file under Deploy.cltProxyPort and Deploy.cltProxyHost.

Migration Help

The following wrapper scripts have been included with OpenDeploy to ease the migration of existing implementations that invoke the original Java-based command-line tools, but want to leverage the new non-Java based command-line tool:

iwodstart (iwodstart.bat for Windows)

iwodschedadd (iwodschedadd.bat for Windows)


• • • •••

Deploy through a Firewall

iwodserverstatus (iwodserverstatus.bat for Windows)

These scripts are implemented as samples. Note that iwodstart and iwodschedadd are not applicable on an OpenDeploy receiver.

These scripts reside in: od-home/solutions/clt

To use the wrapper scripts

1. Make a backup copy of the original command-line tool, which resides in: od-home/bin

2. Place the new script implementation in the od-home/bin directory.

If there are other original command-line tools you want to leverage the iwodcmd approach, use these wrapper scripts as examples to create new wrappers. Only a subset of the command-line tools can be wrapped. Run the iwodcmd -h command for more information on which tools are supported. To create new wrappers, the only change that is required is to update the ACTION variable in the script to specify the desired original command-line tool name.

Deploy through a FirewallFor the most part, the firewall server is transparent to the deployment process. Only in host matching does the firewall impact the deployment and its configuration.

Configuration Requirements

If an OpenDeploy server deploys content through a firewall, you must configure your OpenDeploy environment in the following manner.

The port number you assigned the OpenDeploy server (by default port 20014) must be open on the firewall.

The nodes configuration file (by default odnodes.xml) on the source server must contain the target server’s IP address or host name.

The base server or receiver configuration file of the target server (by default odbase.xml or odrcvr.xml) must contain the target host’s IP address or host name as the localNode element’s host attribute value.

The base server or receiver configuration file of the target server must also include the firewall’s IP address or host name as an allowed host if the firewall is configured for network address translation (NAT). Within the allowedHosts element, you must assign the


• • • •••


16

firewall’s IP address or host name as the node element’s host attribute value. See “Specify Allowed Hosts for Received Deployments” on page 190 for more information.

If the firewall is not configured for network address translation, the target specifies the sender’s address as an allowed host as if there was no firewall present.

Your additional RMI ports must be properly configured if you want the OpenDeploy administration server to access OpenDeploy server nodes on the opposite side of the firewall. OpenDeploy assigns default numbers to these RMI ports, but you can customize them to meet your enterprise’s needs. See “Configure RMI Ports for Administration through a Firewall” on page 134 for more information.

Host Matching

Host matching through a firewall varies depending on whether network address translation (NAT) is used:

If the firewall does not employ NAT, host matching is done against the localNode element’s host attribute value in the deployment configuration, or the source host’s IP address.

If the firewall employs NAT, the firewall host’s IP address is used, rather than the source host’s, during host matching.

If you deploy files through a firewall that uses NAT and not using strict partner checking, you should include the firewall’s outgoing port IP address as an entry, as well as the source server host’s name, in the target’s allowed hosts list. See “Host Checks during Deployments” on page 177 for more information on strict partner checking.

Back up OpenDeploy FilesThis section outlines backup and recovery procedures of your OpenDeploy product installation. It includes the files and directories you should back up each OpenDeploy software component. Some files apply to all platforms, while others are specific to only Windows or UNIX hosts.

You must stop the service or daemon associated with each OpenDeploy component before backing up any of the files associated with the component. Performing the backup while a component is running may pick up files that are dynamically created, which can cause problems during restoration of the backup.

You can use your OpenDeploy backup files for the following conditions:

When the OpenDeploy server is running normally: you want to restore OpenDeploy back to the state it was in at the time of the last backup.


• • • •••

Back up OpenDeploy Files

When the OpenDeploy server is not running normally: you want to restore OpenDeploy back to the state it was in at the time of the last backup to resume normal functioning. If this does not resume normal functioning, you might need to reinstall OpenDeploy, and subsequently restore your backed-up files.

NOTE

If you reinstall the OpenDeploy software to another file system location or host, some files may need to be reconfigured. See the next sections for each component for more information.

Base Server and Receiver

Stop your OpenDeploy service or daemon prior to backing up your base server or receiver files.

Back up the following files and directories for all base server and receivers:

od-home/(od-instance)/db (entire directory)

This directory holds all the schedule, roles and event reporting information.

These items in the od-home/(od-instance)/etc directory:

All XML-based configuration files

deploy.cfg file

These files are the OpenDeploy base server and receiver configuration files.

These items in the od-home/(od-instance)/conf directory (base server only):

All XML-based files

These are all the deployment configuration files.

Any other important customized files.

Startup and system files. You should back up the following additional base server and receiver files:

Windows

• od-home/lib/dbtool.bat

• od-home/install (entire directory)

UNIX

• od-home/etc/init.d/iwodserver

• od-home/startod

• od-home/lib/dbtool

• od-home/lib/iwodrunenv.sh

• od-home/install (entire directory)


• • • •••


16

• /etc/defaultiwodhome

• /etc/init.d/iwodserver

If you plan to reinstall the failed OpenDeploy base server or receiver in a different location or on a different host, you should not restore files listed in this list. These files are generated properly during product installation.

Administration/Report Server

Stop your administration server service or daemon before backing up your administration/reporting server files.

Back up the following files and directories for all administration/reporting server servers:

admin-home/odadmin/db directory (entire directory)

This directory holds all the event reporting database files if your are using the bundled Hypersonic demonstration database. It also contains all the SQL files for the reporting server.

If you use a different database, back the files associated with your database as well.

admin-home/odadmin/config directory (entire directory)

These are the server configuration files.

admin-home/servletd/conf/server.xml

admin-home/httpd/iwwebapps/opendeploy/WEB-INF/conf/framework.properties

Any other important customized files.

Startup and system files. You should back up the following additional administration/reporting server files:

Windows

• admin-home/odadmin/install (entire directory)

UNIX

• admin-home/servletd/bin/iwodadmin

• admin-home/odadmin/install (entire directory)

• /etc/defaulttomcathome

• /etc/init.d/iwodadmin

If you plan to reinstall the failed OpenDeploy administration/reporting server in a different location or on a different host, you should not restore files listed in this list. These files are generated properly during product installation.


• • • •••

Internationalization

Recovery Procedure

To recover backed up OpenDeploy component files and directories

1. Shut down the OpenDeploy component by stopping its associated service or daemon.

2. (If needed) Reinstall the OpenDeploy component software.

3. Restore the backed up files and directories as necessary (see details in the previous sections).

4. Start the OpenDeploy component by restarting the associated service or daemon.

InternationalizationUse the information in this section if you run OpenDeploy on a localized operating system.

Service Configuration File Format

The service configuration file (deploy.cfg) must be in ASCII text. Non-ASCII characters are not allowed.

Encoding for XML-based Configuration Files

The following XML-based server configuration files can use encoding in formats other than UTF-8.

Base server configuration file (by default odbase.xml)

Receiver configuration file (by default odrcvr.xml)

Nodes configuration file (by default odnodes.xml)

All deployment configuration files

For example, if a value in the file contains Japanese characters, the encoding needs to be: <? xml version="1.0" encoding="SHIFT_JIS" ?>



• • • •••


16

Verify 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 is used by default.

Configure File Descriptor Limits on Solaris

OpenDeploy honors adjustments to the Solaris operating system configuration to increase the file descriptor limit beyond its default limit. Increasing the file descriptor limit allows a larger number of sending and receiving legs for all active deployments on one system. Modification of the file descriptor limit is done in the following file: /etc/system

You must add the following lines: set rlim_fd_max=fd-limit

set rlim_fd_cur=fd-limit

where fd-limit is the limit you want. You must reboot the Solaris host following modification of the file descriptor limit.

Be careful when setting higher descriptor limits, as it can sometimes cause booting problems. Refer to the Solaris operating system documentation for more information.

SNMPOpenDeploy provides an SNMP agent that optionally runs independently with each base server or receiver instance. Using an SNMP-enabled network management tool, you can configure your monitoring environment to observe the status and activity of multiple OpenDeploy servers at once. These activities can include which OpenDeploy instances start, stop, or participate in deployments. From your monitoring console, you can also send commands to each OpenDeploy instance, such as to start up or shut down.

Additionally, you can configure OpenDeploy to send an alert to the monitoring console if a failure occurs. For example, if a receiver goes down unexpectedly, the corresponding SNMP agent detects this and dispatches an alert. Upon receiving this alert, you can use the OpenDeploy browser-based user interface to address the problem.

Refer to the OpenDeploy Release Notes to see which versions of SNMP are supported.


• • • •••

SNMP

Start and Stop SNMP

By default, SNMP does not start when OpenDeploy runs for the first time after installation, however, the SNMP agent can be started at any time, either through the Windows Services window or from the Windows or UNIX command line. See “Start OpenDeploy” on page 45 and “Stop OpenDeploy” on page 49 for more information.

Configure SNMP for OpenDeploy Instances

When you create a new OpenDeploy instance, an SNMP agent is configured for that instance. The properties file associated with that instance includes the following SNMP attributes:

MYSNMPREQUESTPORT: specifies the request UDP port of the network manager. The SNMP agent instance contacts the port specified here.

MYSNMPTRAPPORT: specifies the trap UDP port of the SNMP agent instance.

You must provide valid values for these attributes for the instance’s SNMP to work properly.

See “Properties File” on page 54 for more information on the properties file.

Enable and Disable SNMP

You can configure an instance’s SNMP service or daemon to start or to be disabled when the OpenDeploy server starts, both when the instance is created, and for an existing instance.

Instance Creation

When you create a new OpenDeploy instance, you have the option to enable or disable SNMP with that instance at startup through the instance’s properties file. The properties file contains the ENABLESNMPINSTANCE attribute, which specifies whether the SNMP agent for this instance starts automatically when the server starts. If a valid choice is not specified, the SNMP agent does not start. See “Properties File” on page 54 for more information on the properties file.

Existing Instances

If you want to change the enabled or disabled status of an existing instance’s SNMP, you can run the iwodinsttool command at the prompt. See “Disable SNMP” on page 59 and “Enable SNMP” on page 59 for more information.


• • • •••


16

SNMP Agent Configuration

The SNMP agent has an associated SNMP agent configuration file that contains settings that define the communication and security between the SNMP network manager and the associated OpenDeploy instance. This file resides in: od-home/(od-instance)/etc/odsnmp.xml

The SNMP agent configuration file is structured as: <snmpAgentConfiguration>

<agentProperties

agentName="mars_marketing_OpenDeployAgent" requestPort="161"

trapHost="mars" trapPort="162" bufferSize="4096" odHostName="mars"

odRmiPort="9183" odInstanceName="marketing"

logPath="C:\Interwoven\OpenDeployNG\inst\marketing\log"/>

<securityProperties community="opendeploy" allowSet="no">

<node host="jmoorebw2k"/>

</securityProperties>

</snmpAgentConfiguration>

The snmpAgentConfiguration element is the root container for the configuration.

SNMP Agent Properties

Within the snmpAgentConfiguration element is the agentProperties element: <snmpAgentConfiguration>

<agentProperties

agentName="mars_marketing_OpenDeployAgent" requestPort="161"

trapHost="mars" trapPort="162" bufferSize="4096" odHostName="mars"

odRmiPort="9183" odInstanceName="marketing"

logPath="C:\Interwoven\OpenDeployNG\inst\marketing\log"/>

...


The agentProperties element defines the method in which the SNMP agent interacts with the SNMP network manager and the OpenDeploy instance. The agentProperties contains the following attributes:

agentName: Specifies the unique name of the agentProperties element.

requestPort: Specifies the listening UDP port for receiving requests from the SNMP network manager.

trapHost: Specifies the host name or IP address of the SNMP network manager host.

trapPort: Specifies the UDP port number for the SNMP network manager host.

bufferSize: Specifies the number of bytes that the SNMP packet should be.


• • • •••

SNMP

odInterval: Specifies the number of minutes between the times that the SNMP agent polls the status of the OpenDeploy server instance. The default value is 5. See “Set up SNMP Polling” on page 169 for more information on this feature.

odHostName: Specifies the resolvable host name or IP address of the OpenDeploy server host. If your host has multiple IP addresses (with one or multiple network interface cards), you must specify an IP address rather than the host name.

odRmiPort: Specifies the RMI registry TCP port used by the OpenDeploy service or daemon.

odInstanceName: Specifies the name of the OpenDeploy server instance.

logPath: Specifies the full path to the directory containing the OpenDeploy SNMP log file. For example:

logPath="od-home/log"

Set up SNMP Polling

You should consider the OpenDeploy completion queue when determining how frequent to set the SNMP agent polling interval (as specified by the agentProperties element’s odInterval attribute value). Because the SNMP agent relies on the completed deployment list for determining deployment status information, if the completed queue size (as specified by the completedQueueCapacity attribute associated with the initiatorProperties and listenerProperties elements in the OpenDeploy server configuration file) is exceeded, items fall off the list, resulting in data not being seen by the SNMP agent.

For example, if the completed queue size (completedQueueCapacity attribute) value is 50, and the SNMP polling interval (odInterval attribute) is set to every 5 minutes, if 51 deployments complete within 5 minutes, one of the deployments is missed by the SNMP agent.

See “Specify the Completed Deployments List” on page 197 for more information on configuring the completed queue size on an OpenDeploy server.

Logs

Each OpenDeploy instance’s SNMP agent has it own logging file. The log file records all SNMP agent related activities, such as the network manager access log, OpenDeploy availability status, and error messages.

By default, the SNMP agent log file resides in: od-home/(od-instance)/log/odsnmp.log

The SNMP agent log file’s name is fixed as odsnmp.log and cannot be changed, however, you can specify a location other than the default location by modifying the agentProperties element’s logPath attribute, for example:


• • • •••


17

<agentProperties ... logPath="od-home/log/snmplog"/>

which results in the log having the following path: od-home/log/snmptlog/odsnmp.log

Security

Within the snmpAgentConfiguration element is the securityProperties element. It controls certain SNMP security measures: <snmpAgentConfiguration>

...

<securityProperties community="opendeploy" allowSet="no">

...


The securityProperties contains the following attributes:

community specifies the SNMP community, a password-like string value that must be provided by the SNMP network manager whenever polling on an OpenDeploy server by the network manager takes place.

allowSet specifies whether (yes or no) the SNMP Set command is enabled. The Set command is used for starting and stopping servers under the control of the SNMP network manager. The default value is no.

SNMP security is further defined within the securityProperties element through the node element. <securityProperties community="opendeploy" allowSet="no">

<node host="SNMP_network_manager_host"/>


The node element identifies the SNMP network manager host that is allowed to control the OpenDeploy server host. The node element’s host attribute specifies the resolvable host name or IP address of the SNMP network manager host, for example:

<node host="mars"/> or <node host="114.342.23.20"/>

If you want your OpenDeploy server host to be managed by more than one SNMP network manager, you must specify a separate node element for each network manager host, for example: <securityProperties community="opendeploy" allowSet="no">

<node host="mars"/>

<node host="venus"/>



• • • •••

SNMP

Note that the same security properties measures apply to all the SNMP network manager hosts you specify.

Disable Alert Notifications

By default the OpenDeploy SNMP agent sends the alert notifications to the SNMP network manager under the following conditions:

when the OpenDeploy server goes down or does not respond

when deployments fail

You can disable any alert notifications by configuring the alertList element within the snmpAgentConfiguration element: <snmpAgentConfiguration>

...

<alertList>

...

</alertList>


The alertList element can contain an alert element for any specific notification alert you want to disable. Each alert element contains the following attributes:

name: specifies one of the following alert notification options to disable: ON_SERVER_STOP

ON_FAILED_DEPLOYMENT

status: indicates whether the alert notification specified in the name attribute is enabled (on) or disabled (off).

For example, to disable the alert notification that occurs when the OpenDeploy server goes down or does not respond, make the following configuration: <alertList>

<alert name="ON_SERVER_STOP" status="off"/>

</alertList>

To disable the alert notifications when deployments fail, add a corresponding alert element: <alertList>

<alert name="ON_SERVER_STOP" status="off"/>

<alert name="ON_FAILED_DEPLOYMENT" status="off"/>

</alertList>

Because all the alert notifications are enabled by default, you only need to configure the alertList and alert elements if you want to disable one or more alert notifications. If you want to keep all of the alerts enabled, you do not have to perform any configuration.


• • • •••


17

Object IDs

The following list provides the SNMP object IDs (OIDs) used with OpenDeploy.

Get OIDs

ODServerStatusMib: 1.3.6.1.4.1.18783.100.6.0

receivingDeployLoadMib: 1.3.6.1.4.1.18783.100.5.0

sendingDeployLoadMib: 1.3.6.1.4.1.18783.100.4.0

Set OIDs

ODServerStopMib: 1.3.6.1.4.1.18783.100.9.0

Note that setting the MIB Entry to 0 requests a stop server. Setting the entry to 1 requests a start server.

Trap OIDs

deployfailedTrap: 1.3.6.1.4.1.18783.100.10.0

ServerStoppedTrap: 1.3.6.1.4.1.18783.100.16.0

Note that the IANA assigned the private enterprise number 18783 to Autonomy Interwoven.

Management Information Base Support

OpenDeploy provides a Management Information Base (MIB) file (iwopendeploy.mib). A MIB is an ASCII text file that describes the SNMP messages and traps that OpenDeploy understands as a list of data objects. It is a dictionary of the SNMP language where every object referenced in SNMP messages sent or received by the OpenDeploy server is listed in the MIB. The MIB resides in: od-home/snmp

The main purpose of the MIB is to translate numerical strings into human-readable text. When an OpenDeploy server sends a Trap or other message, it identifies each data object in the message with a number string called an object identifier (OID). The MIB provides a text label called for each OID. An SNMP manager uses the MIB as a codebook for translating the OID numbers into a human-readable display. As an SNMP manager, you need the MIB to process and understand messages from OpenDeploy servers.

When planning for SNMP monitoring of OpenDeploy running nodes, refer to the MIB to determine which SNMP capabilities the OpenDeploy servers has.

To integrate MIB into the SNMP manager requires compiling MIB from its raw ASCII format into a binary format the SNMP manager can use to remote control the OpenDeploy server.


• • • •••

Configure DAS for TeamSite

Configure DAS for TeamSiteIf you installed OpenDeploy on a host with a TeamSite release already installed, you may have to perform additional configuration of the OpenDeploy software. This depends on the TeamSite release and the type of OpenDeploy installation. This configuration is required to use Database Auto Synchronization (DAS).

No configuration is required under the following installation or upgrade scenarios:

fresh installation of this release of OpenDeploy on a host with any compatible TeamSite release

upgrade to this release of OpenDeploy from OpenDeploy 5.x on a host with any compatible TeamSite release

upgrade to this release of OpenDeploy from OpenDeploy 6.0 on a host with any compatible TeamSite release prior to 6.5

Configuration is required if you upgrade to this release of OpenDeploy from OpenDeploy 6.0 on a host with TeamSite 6.5 or later. You must open the daemon.cfg file and update several of the attribute values associated with the DAS: Configuration section for subscribing to the TeamSite event-subsystem. Do not confuse this section in the daemon.cfg file with the subsequent section on DAS event reporting.

To update the daemon.cfg file

1. Open the daemon.cfg using a text editor. This file resides in: od-home/(od-instance)/etc

2. Under the event-subsystem element (the one associated with subscribing to the TeamSite subsystem), update the property element associated with the jmsclasspath to reflect the following value: <event-subsystem>

...

<property name="jmsclasspath"

value="iw-home/eventsubsystem/lib/openjms-client-0.7.6.1.jar"/>

...

<event-subsystem>

where iw-home is the TeamSite home directory.

3. Under the same event-subsystem element, update the property element associated with java.naming.provider.url to reflect the following value: <property name="java.naming.provider.url"

value="tcp://localhost:3035/JndiServer"/>

Note that 3035 is the default port number for the TeamSite event subsystem JNDI server. If you chose another port number for this server when you installed TeamSite, you must use that port number value here.


• • • •••


17

4. Under the same event-subsystem element, update the property element associated with java.naming.factory.initial to reflect the following value: <property name="java.naming.factory.initial" value="org.exolab.jms.jndi.InitialContextFactory"/>

5. Save and close the daemon.cfg file.

6. Restart the OpenDeploy server instance.


• • • •••

Chapter 4

Server Configuration Files

Each instance of the OpenDeploy base server or receiver has an associated server configuration file. By default, these server configuration files have the following names:

Base server: odbase.xml

Receiver: odrcvr.xml

You have the option of renaming these files, but the name change must be reflected in the server’s associated service configuration file (deploy.cfg). See “Specify the Base Server and Receiver Configuration Files” on page 132 for more information.

The server configuration file resides in:

od-home/(od-instance)/etc

Base server and receiver files are XML-based files that contains elements and attributes that determine the features and functionality of the server instance. These features can include:

encoding

communicating with other OpenDeploy software components and nodes

enabling target-side Deploy and Run

specifying the deployment manifest stream format

scheduling information

allowed access for other source hosts to this OpenDeploy server host

logging defaults

encryption settings

deployment queueing

specifying the completed deployments list

Web services


• • • •••

Chapter 4: Server Configuration Files

17

database deployments

performance throttling

In some cases, these elements and attributes whose values serve as default settings in case a given deployment configuration does not specify a needed value. You can modify the file to meet your specific deployment needs.

Typically, after the server configuration file is configured, you do not have to modify it again unless there are changes to your server or to the network over which it deploys files.

EncodingThe encoding for the server configuration files can be encoding other than UTF-8. For example, if a value in the file contains Japanese characters, the encoding needs to be: <? xml version="1.0" encoding="SHIFT_JIS" ?>


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 is used by default.

Identify the HostThe host’s identify is determined by the localNode element’s host attribute value. <deployServerConfiguration>

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

...

</deployServerConfiguration>

The localNode element contains the following attributes:

name: denotes the unique name of the localNode element. Use of the name attribute is often required for routed deployments.

host: specifies the resolvable host name or IP address of the OpenDeploy server. For example:

host="venus.mycompany.com" or host="114.342.23.21"


• • • •••

Specify the Communication Port

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.

Specify the Communication PortThe OpenDeploy server uses the bind port to communicate with other servers when comparing files and when sending and receiving deployed files. The bind port number is listed in the base server configuration file, where it is specified as the listenerProperties element’s bindPort attribute. For example: <deployServerConfiguration>

...

<listenerProperties name="InterwovenOpenDeploy" bindPort="20014"

.../>

...


The name attribute value is fixed as InterwovenOpenDeploy. The default bind port is 20014, but you can set it to any available port. If the bind port value is changed, any other source server deploying to your OpenDeploy server must update its node configuration file with this new port value. For ease of port management, you might want to use the same bind port number for all of your OpenDeploy servers. The bind port value is also used in other configurations, such as the nodes configuration file.

Host Checks during DeploymentsBy default, authentication of the source host is performed with strict partner checking disabled. With strict partner checking disabled, the receiver attempts to match (case insensitively) the localNode element’s host attribute string value in the deployment configuration with an allowed host entry. If no match is found, the receiver attempts to match the socket IP address with an allowed host entry. Note that if the host attribute’s value is numeric, it is still treated as a string value, and only a string match is performed. There is no requirement for this value to be a valid host name or address.

With strict partner checking enabled, the sender authentication check is tightened. Here, a socket IP address match is forced, ensuring the uniqueness of the sending host. The IP address must match or resolve to the allowed host entry. The localNode element’s host attribute value in the deployment configuration is not included in the matching. You enable strict partner checking by


• • • •••


17

specifying a value of yes for the listenerProperties element’s strictPartnerChecking attribute. For example: <listenerProperties ... strictPartnerChecking="yes" .../>

For reverse deployments, the reverse source attempts to match (case insensitively) the localNode element's host attribute in the deployment configuration file with an allowed host entry. The reverse source server does not allow the connection if the initiating server host is not present in the reverse source host's allowed host list.

Specify Alternate Locations for Temporary Deployment Files

When an OpenDeploy target receives a deployment, temporary files associated with the deployment are written to the target file location. You have the option of designating an alternate location on the target server for the temporary files. Specifying an alternate file location can eliminate unnecessary file activity for services and programs, such as an automatic indexer, that are sensitive to the presence of new files.

You can specify the full path to an alternate location on the server as the value of the listenerProperties element’s transientDirectory attribute. For example: <deployServerConfiguration>

...

<listenerProperties ... transientDirectory="/tmp/temp_files" ..."/>

...


Using this feature does not change the deployment behavior of OpenDeploy, but it can result in slower performance.

On UNIX servers, performance degradation differs depending on where the alternate file location resides:

If the alternate temporary file location resides on the same file system as the target file location, performance degrades somewhat.

If the alternate temporary file location resides on a different file system than the target file location, performance degrades further.

On Windows servers, performance degradation differs depending on where the alternate file location resides:

If the alternate temporary file location resides on a local drive, performance degrades somewhat.


• • • •••

Enable Concurrency Management

If the alternate temporary file location resides on a remotely mounted drive, performance degrades further.

NOTE

You cannot use this feature when deploying TeamSite EAs to a TeamSite target. Refer to “Deploying TeamSite Extended Attributes with TeamSite Files” in the OpenDeploy Deployment Configuration Guide for more information on this feature.

Enable Concurrency ManagementConcurrency management addresses potential conflicts and collisions resulting from simultaneous receipt of like-named files deployed into the same target file location. These problems can occur under the following situations:

multi-definition deployments where the definitions share colliding target directories (across-parallel-legs)

multi-path definitions where the source-target pairs share colliding target directories (within a leg)

multiple independent deployments that each have a definition with colliding target directories

Concurrency management prevents these conflicts by allowing only one deployment leg to have access to a given target directory path sequence at any given time. This path sequence includes both parent and child paths of the target path. Other deployment legs attempting to deploy to that directory are blocked.

Concurrency management is enabled in the pathRegistryChecking attribute in the listenerProperties element of the target OpenDeploy server’s base server or receiver configuration file: <deployServerConfiguration>

...

<listenerProperties ... pathRegistryChecking="yes"/>

...


Specify a pathRegistryChecking attribute value of yes to enable concurrency management, or no to disable this feature. The default value is no.


• • • •••


18

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. After each check, the deployment reports its status back to the sending server. Default value is 30 seconds.

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

In the following example: <deploymentConfiguration>

<localNode host="mars" blockCheckInterval="5"

blockMaxWaitTime="300"/>

...

</deploymentConfiguration>

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

Deployment legs that are blocked due to the concurrency management feature are indicated in the Details section of the Source Deployment and Target Deployments windows in the browser-based user interface.

A blocked deployment leg also logs that it is attempting to access a target directory in the deployment log file.

A blocked deployment can be cancelled before the maximum waiting time is reached.

The localNode element also supports a timeout attribute for connection socket inactivity. You should always configure a blockCheckInterval attribute value smaller than the timeout attribute value. Refer to “Specifying the Connection Timeout” in the OpenDeploy Deployment Configuration Guide for more information.

Concurrency management does not address conflicts that can occur when multiple instances of the OpenDeploy server on the same host receive simultaneous incoming deployments that write to the same target file location.


• • • •••

Clear the Registry of Target Path Entries

Clear the Registry of Target Path EntriesConcurrency management maintains a registry of target deployment paths that are accessed by active deployments. Entries in this registry can block subsequent deployments to the same target path.

You can clear some or all of the target paths in the registry using the iwodcmd serverreset command-line tool and the -clearregpath pattern option:

iwodcmd serverreset -clearpathreg pattern or iwodcmd serverreset [-odinst instName] -clearpathreg pattern

where -odinst instName is a particular OpenDeploy server instance, and pattern is a path string with support for (“*”) wildcards. The target path entries in the registry that match the pattern value are cleared.

You must include the entire pattern value in quotes if any wildcards are included. For example, -clearpathreg "/a/b/c/*" clears all path entries in the registry with the parent path /a/b/c, including a/b/c itself. If no pattern is specified, all paths are cleared.

Allow Traversal of Target Links in File List Deployments

A target OpenDeploy server running on a UNIX host may be configured to allow traversal of target-side symbolic links. To use this feature, 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: <deploymentConfiguration>

...

<listenerProperties ... allowTargetFollowLinks="yes"/>

...


By default, the allowTargetFollowLinks attribute value is no. If this value is set to no, or if the allowTargetFollowLinks attribute is missing from the server configuration, then you cannot use this feature.


• • • •••


18

NOTE

This feature allows a deployment to bypass the allowed directories check. Therefore, use of this feature is discouraged.

Refer to “Configuring File List Deployments for Traversal of Target-Side Links” in the OpenDeploy Deployment Configuration Guide for more information.

Set the File Transport Buffer SizeYou can set a default buffer size in bytes for transporting files to and from your OpenDeploy server, allowing you to throttle the bandwidth consumption. This amount is specified in the transportProperties element’s bufferSize attribute. For example: <deployServerConfiguration>

...

<transportProperties name="od" bufferSize="8000" .../>

...


The transportProperties element also contains the name attribute. This attribute must be included in the deployment configuration, but can only have the value of od.

Restrict Access to Users with OpenDeploy Roles

A user can access an OpenDeploy server and run deployments without having an assigned role on that server. Users without assigned roles can also access the OpenDeploy server host’s file system using OpenDeploy RMI APIs. You can restrict OpenDeploy access to only those users with roles on that server by enabling the strict authentication feature on the appropriate server.

To enable this feature, the listenerProperties element’s strictAuthentication attribute in the OpenDeploy server’s base server or receiver configuration files must have a value of yes, for example: <deploymentConfiguration>

...

<listenerProperties ... strictAuthentication="yes"/>


• • • •••

Restrict Access to Users with OpenDeploy Roles

...


By default, the strictAuthentication attribute value is no.

When this feature is enabled, all clients that use the OpenDeploy API interfaces to get access to the OpenDeploy server need to pass CSContextString as when creating IWUser object. CSContextString can be obtained using the ContentServices Foundation (CSF) Access service, or using CSSDK if TeamSite is passing user credentials to either of the service.

Values for the username, role, and other attributes contained in CSContextString is obtained from the passphrase file, which resides in: od-home/(od-instance)/etc

Without the presence of this file, no user attributes can be access and authentication fails. See “Access Service Management” on page 129 for more information.

For more information on features enabled by strictAuthentication flag see “strictAuthentication” on page 276.

Invoke from a TeamSite Workflow External Task

You can use the -session parameter with the iwodstart or iwodcmd start command-line tools to pass CSContextString values to the OpenDeploy server. Use this option when a TeamSite workflow external task invokes the iwodcmd start or iwodstart command and the strictAuthentication attribute is enabled on the OpenDeploy server.

To get CSContextString in an external task, an environment variable IWAUTH contains the value of CSContextString. The following example shows how to retrieve the CSContextString value: my $csContextString = $ENV{"IWAUTH"};

Here is an example of how the -session parameter passes CSContextString values to the OpenDeploy server for authentication: iwodcmd start test -session $ csContextString

Enable Authentication when iwodcmd Commands Run

If you run iwodcmd commands under strict authentication, you must ensure that the OpenDeploy servers service configuration file’s (deploy.cfg) Deploy.cltProxyAuthCheck property is set to y, for example: Deploy.cltProxyAuthCheck: y


• • • •••


18

See “Modify the Service Configuration File” on page 131 for more information.

Use Strict Authorization in ControlHub

If you use OpenDeploy as part of ControlHub, you must perform the following authorization tasks depending on the type of deployment you want to run.

Authorization when Running Deployments

If you run deployments from ControlHub under strict authentication, you must use the iwodauthorize command-line tool for authorization. Specify the category/project name before the deployment, for example: iwodauthorize –d add INTERWOVEN\\jdoe ajubaBank--sampleProj–1004/

demo_aggregation_tier1.xml

where INTERWOVEN\\jdoe is an authorized user with the role od-user on the OpenDeploy server.

Authorization when Running Select and Deploy

If you run deployments using the Select and Deploy feature in ControlHub under strict authentication, you must use the iwodauthorize command-line tool with the iwselectdeploy/select_deploy option for authentication. For example: iwodauthorize -d add INTERWOVEN\\bill iwselectdeploy/select_deploy

where INTERWOVEN\\jdoe is an authorized user with the role od-user on the OpenDeploy server.

Set the Number of Connection RetriesNOTE

This feature only applies to the base server.


• • • •••

Enable Target-Side Deploy and Run

You can specify the number of times the base server attempts to establish a connection with a target server before timing out. This number is specified in the connectRetries attribute of the transportProperties element. For example: <deployServerConfiguration>

...

<transportProperties ... connectRetries="10"/>

...


The default value is 3. If the connectRetries attribute is not specified in the base server configuration, OpenDeploy uses the default value.

Enable Target-Side Deploy and RunDeploy and Run is a feature allows you to associate scripts that trigger under specified conditions during the course of a deployment. Deploy and Run triggers can be configured to occur both on the sending (source) side and the receiving (target) side. You can configure your OpenDeploy server receiving a deployment to allow or prevent the triggering of any target-side Deploy and Run triggers in the dnrProperties element’s allowDnrExecution attribute: <deployServerConfiguration>

...

<dnrProperties allowDnrExecution="yes" ...>

...


A value of yes (default) allows target-side Deploy and Run triggers to occur, while a value of no prevents them. Refer to “Deploy and Run” in the OpenDeploy Deployment Configuration Guide for more information on this feature.

Specify the Deployment Information Stream Format

OpenDeploy generates an internal list of path items deployed or to be deployed each time a deployment runs. This data can be streamed into Deploy and Run scripts. After the stream is used by the Deploy and Run script, you can manipulate it to meet your needs. Refer to “Usage of the Deployment Information Stream” in the OpenDeploy Deployment Configuration Guide for more information on this feature.


• • • •••


18

OpenDeploy currently contains a method of capturing this streamed information into a new manifest format. Older releases of OpenDeploy used a legacy log format for this streamed information. Both methods are supported. New OpenDeploy installations use the manifest format by default. Upgrades from previous OpenDeploy releases use the legacy log-based format by default to retain backward compatibility for existing Deploy and Run scripts that use the log-based format.

You have the option of using either format. You can specify the format you want in the dnrProperties element’s infoStreamFormat attribute: <deployServerConfiguration>

...

<dnrProperties allowDnrExecution="yes" infoStreamFormat="manifest">

...


Select manifest for the manifest format, or log for the log format.

New installations have the infoStreamFormat attribute included in the dnrProperties element automatically. Upgrades from previous releases do not. If you have upgraded from a previous release and you want to use the manifest format, you must manually add the infoStreamFormat attribute and its manifest value to the dnrProperties element in your server configuration file using a text or XML editor.

If you enable the reporting feature, OpenDeploy automatically outputs the information stream in the manifest format, even if you upgraded from a previous release or your infoStreamFormat attribute value is log. You must ensure the reporting feature is disabled to use the log format. See “Reports” on page 195 for more information about enabling the reporting feature.

Define the Scheduler DatabaseNOTE


The OpenDeploy base server software requires a JDBC-compliant database to allow scheduling information to be stored in cases of server shutdown or similar situations. During installation, you receive a prompt as to whether you want to use the default database included with the OpenDeploy software or use a different one of your own. The database packaged with OpenDeploy is Hypersonic SQL. You can reconfigure the OpenDeploy base server configuration to access a different database through the schedulerProperties element. <deployServerConfiguration>

...


• • • •••

Define the Scheduler Database

<schedulerProperties .../>

...


The schedulerProperties contains the following attributes:

jdbcDriverClass: type the JDBC Java class that communicates to the RDBMS. The default value is org.hsql.jdbcDriver, the Hypersonic SQL database.

dbUrl: Type the Web URL to the scheduler database. See “URL Choices” on page 187 for more information.

dbUser: Type the user account name for access to the scheduler database.

dbPassword: Type the password to the scheduler database.

isClearPassword: Indicate whether the value of the dbPassword attribute is contained as unencoded plain text in the deployment configuration file. By default, the dbPassword value is an encoded string, however, if the isClearPassword attribute value is yes, this password is in plain text. The default implied value is no. The Hypersonic SQL database that is installed with the base server software does not require a password.

hsqlScriptSize: Indicate the size in megabytes the scheduler script file (scheddb.script) can grow. See “Limit the Size of the Scheduler Script File” on page 190 for more information. This is an optional attribute. If no value is specified, OpenDeploy uses the default value of 2.

The default configuration for the Hypersonic SQL database is as follows: <schedulerProperties

jdbcDriverClass="org.hsql.jdbcDriver"

dbUrl="jdbc:HypersonicSQL:od-home/db/schedDB"

dbUser="sa"

dbPassword=""/>

If you use a database other than the default Hypersonic RDBMS with the OpenDeploy scheduler, and you shut down or restart that database, you must also restart the OpenDeploy base server to establish a fresh connection.

URL Choices

You have two choices for values in the dbUrl attribute when you use the default Hypersonic SQL database:

in-memory

standalone (required to allow your scheduled entries to persist across restarts)

If you use another database, these features are not available.


• • • •••


18

In-Memory Database URL

The URL for an In-Memory database is: jdbc:HypersonicSQL:.

If you use In-Memory, the data is lost if the server quits.

Standalone URL

In a standalone URL, the server stores the data in flat files. If the server restarts, the data is not lost.The URL for the standalone database is: jdbc:HypersonicSQL:db_name

where db_name is the filename, including path, of the database you entered or accepted during installation.

The database connects with the following files created in the location where the server started: db_name.properties

db_name.data

db_name.script

The default database that comes with OpenDeploy has the following value: dbURL="jdbc:HypersonicSQL:od-home/db/schedDB"

and connects with the following files: schedDB.properties

schedDB.data

schedDB.script

If you entered your own database foo, the dbURL attribute is: dbURL="jdbc:HypersonicSQL:path/foo"

and connects with the following files: foo.properties

foo.data

foo.script

created in the home directory for foo.


• • • •••

Define the Scheduler Database

Use Third-Party JDBC Drivers with the OpenDeploy Scheduler

To use third-party JDBC drivers with the OpenDeploy scheduler

1. Shut down the OpenDeploy base server by stopping its service or daemon.

2. Manually create the table entries in the database. The data definition language (DDL) scripts needed for creating the table are listed in the next section.

3. Provide driver-specific information in the schedulerProperties element of the base server configuration file. This element contains the following attributes:

jdbcDriverClass specifies the JDBC Java class that is used to communicate to the RDBMS.

dbUrl specifies the Web URL to the scheduler database.

dbUser specifies the user account name for access to the scheduler database.

dbPassword specifies the password to the scheduler database.

isClearPassword indicates whether the value of the dbPassword attribute is contained as unencoded plain text in the deployment configuration file. By default, it is assumed that the dbPassword value is an encoded string, however, if the isClearPassword attribute value is yes, this password is in plain text. Default value is no.

4. Add the vendor-specific .jar file in the classpath.

The following DDL scripts create the database table entries:CREATE TABLE IWOV_SCHEDULE (PK VARCHAR(128) NOT NULL, SCHEDULED_ITEM TIMESTAMP NOT NULL, TIME_EXPRESSION VARCHAR(128), END_TIME TIMESTAMP, REPEAT_COUNT INTEGER, TYPE VARCHAR(128), CALENDAR VARCHAR(128), STATE VARCHAR(128) NOT NULL, LISTENERS VARCHAR(128), DAYINV VARCHAR(128), DEPLOYNAME VARCHAR(128), DEPLOYSUFFIX VARCHAR(128), DESCRIPTION VARCHAR(128), ENDTIME VARCHAR(128), HOURINV VARCHAR(128), KEYVALUES VARCHAR(128), LOGLEVEL VARCHAR(128), MINUTEINV VARCHAR(128), MONTHDAYS VARCHAR(128), NO_RECUR VARCHAR(128), OWNER VARCHAR(128), PAD1 VARCHAR(128), PAD2 VARCHAR(128), PAD3 VARCHAR(128), PAD4 VARCHAR(128), PAD5 VARCHAR(128), PAD6 VARCHAR(128), RECURSET VARCHAR(128), REPAIR VARCHAR(128), REPEAT VARCHAR(128), STARTDEPLOY BIT, STARTTIME VARCHAR(128), SYNCH VARCHAR(128), VERIFY VARCHAR(128), WEEKDAY VARCHAR(128), WEEKINV VARCHAR(128), YEARINV VARCHAR(128))

CREATE TABLE IWOV_SCHEDULE_PK (NEXT_PK VARCHAR(128) NOT NULL)

CREATE TABLE IWOV_QUEUE (PK VARCHAR(128) NOT NULL, NAME_FK VARCHAR(128) NOT NULL, PRIORITY INTEGER NOT NULL, STATE VARCHAR(128) NOT NULL, DAYINV VARCHAR(128), DEPLOYNAME VARCHAR(128), DEPLOYSUFFIX VARCHAR(128), DESCRIPTION VARCHAR(128), ENDTIME VARCHAR(128), HOURINV VARCHAR(128), KEYVALUES VARCHAR(128), LOGLEVEL VARCHAR(128), MINUTEINV VARCHAR(128), MONTHDAYS VARCHAR(128), NO_RECUR VARCHAR(128), OWNER VARCHAR(128), PAD1 VARCHAR(128), PAD2 VARCHAR(128), PAD3 VARCHAR(128), PAD4 VARCHAR(128), PAD5 VARCHAR(128), PAD6 VARCHAR(128), RECURSET VARCHAR(128), REPAIR VARCHAR(128), REPEAT


• • • •••


19

VARCHAR(128), STARTDEPLOY BIT, STARTTIME VARCHAR(128), SYNCH VARCHAR(128), VERIFY VARCHAR(128), WEEKDAY VARCHAR(128), WEEKINV VARCHAR(128), YEARINV VARCHAR(128))

CREATE TABLE IWOV_QUEUE_NAMES (PK VARCHAR(128) NOT NULL, NAME VARCHAR(128) NOT NULL, STATE VARCHAR(128) NOT NULL)

Limit the Size of the Scheduler Script FileBy default, OpenDeploy uses the HSQL database to support the scheduler. When the HSQL database is used, the scheduler uses the scheduler script file (scheddb.script) to log and track scheduled deployments. If you specify a different scheduler database, the scheduler script file is not used.

The size of this scheduler script file can effect how long it takes for the base server software to start and how much memory is used.Very large scheduler script files can trigger out-of-memory problems, which can occur when frequent scheduled deployments take place.

You can limit the size of the scheduler script file by specifying the size in the hsqlScriptSize attribute. The hsqlScriptSize attribute value specifies the maximum size in megabytes the file can grow. For example: hsqlScriptSize="10"

specifies the maximum size of 10 megabytes. No unit of measure other than megabytes is allowed, and it is not necessary to specify the unit of measure in the value (such as 10 MB). Only whole numbers (no fractions) are supported. OpenDeploy interprets any number you specify as being in megabytes. After this maximum size is reached, OpenDeploy deletes the oldest log entries to make room for the newly added ones. The default value is 2.

The hsqlScriptSize attribute is only used when OpenDeploy uses the default HSQL database. If the hsqlScriptSize attribute value is specified and the HSQL database is not being used, OpenDeploy ignores it.

Specify Allowed Hosts for Received Deployments

You must specify which source server hosts in the OpenDeploy environment can deploy files to your OpenDeploy server in the allowedHosts element.


• • • •••

Specify Allowed Hosts for Received Deployments

<deployServerConfiguration>

...

<allowedHosts>

...

</allowedHosts>

...


When a deployment starts, the receiving server compares the host name of the deploying server (as specified in the host attribute value of the deployment’s localNode element) with the host name values residing within the allowedHosts element. Matches can be made with any combination of case-insensitive host names and IP addresses. In the following example, only the hosts jupiter.mycompany.com and 114.342.23.23 can deploy files to this OpenDeploy server: <allowedHosts>

<node host="jupiter.mycompany.com"/>

<node host="114.342.23.23"/>

</allowedHosts>

Check for Allowed Hosts

When a deployment is initiated, the receiving OpenDeploy server matches the name of the sending server host with each node listed in the allowedHosts element of its base server or receiver configuration file. The host names are compared as case-insensitive strings. If this comparison results in a match, the deployment is allowed to continue.

If the string comparison does not result in a match, OpenDeploy attempts to determine and match the IP addresses of the sending server host with the hosts listed in the allowedHost element. If this comparison results in a match, the deployment is allowed to continue. If the comparison fails, the deployment is not allowed to occur.

Manage IP Address Checks

To ensure that IP address checking occurs, purposely use a mix of DNS names and IP addresses in your configurations. In some cases you may not want IP address checking to occur, such as if you have a DNS problem, or in the case of DHCP where IP changes dynamically. If you do not want IP address checking to occur, use the same host name strings in your source and target configurations.


• • • •••


19

Reverse Deployments

The reverse source server in a reverse deployment must specify the reverse target’s host as an allowed host. Refer Reverse Deployment section in the OpenDeploy Deployment Configuration Guide for more information.

Host Checks

The nodes configuration file (by default odnodes.xml) is clear during reverse deployments. Instead, the reverse source server attempts to match (case insensitively) the localNode element's host attribute in the deployment configuration file with an allowed host entry.

Specify Allowed Directories for DeploymentsYou can match specific target directories on your OpenDeploy server host with each source host listed in the allowedHosts element. This way you can control where deployed files from specific source hosts are placed on your target host.

You must add the allowedDirectories element and at least one occurrence of the path element for each specified node in the allowedHosts element. The path of the allowed directory is specified as the value for the name attribute of the path element.

In the following example, the source server host jupiter.mycompany.com is tasked with deploying monthly reports and the source host 114.342.23.23 is tasked with deploying yearly reports to your target server. <allowedHosts>

<node host="jupiter.mycompany.com">

<allowedDirectories>

<path name="C:\reports\monthly"/>

</allowedDirectories>

</node>

<node host="114.342.23.23">

<allowedDirectories>

<path name="C:\reports\yearly"/>

</allowedDirectories>

</node>

</allowedHosts>

You want their deployed files to be placed only in the following locations:


• • • •••

Logs

jupiter—C:\reports\monthly

114.342.23.23—C:\reports\yearly

To enable this, you have assigned those allowed directories to the allowed hosts. Any attempt by jupiter.mycompany.com or 114.342.23.23 to deploy files to directories other than those assigned in the allowedDirectories element fail.

Figure 44 shows this example:

Figure 44 Allowed hosts and allowed directories

mars

(target server host)

jupiter.mycompany.com

(source server host)

114.342.23.23

(source server host)

jupiter.mycompany.com deploys files to C:\reports\monthly

114.342.23.23 deploys files to C:\reports\yearly

Base server configuration file lists jupiter.mycompany.com and 114.342.23.23 as allowedhosts.

In reverse deployments, the reverse target’s server configuration file must specify all allowed directories that are to receive files from the reverse source. Refer to Reverse Deployments in the OpenDeploy Deployment Configuration Guide for more information.

LogsEach OpenDeploy base server logs its activities to its associated base server log. This log contains entries on activities that occur regarding the base server. See “Logs” on page 233 for more information on logging types and functions.

You can specify default logging values for all deployments that your OpenDeploy base server performs or receives. If a particular deployment configuration has defined its own logging settings, the deployment-based logging settings supersede the default settings you made in the base server configuration file.

Default base server logging is defined in the logRules element: <deployServerConfiguration>


• • • •••


19

...

<logRules

maxBytes="5mb"

maxBackupIndex="100"

directory="C:\Interwoven\OpenDeployNG\log"

level="verbose"/>

...


logRules Element Attributes

The logRules element contains 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 called the rollover threshold. You can specify different byte measurements in the value, including megabytes (mb), kilobytes (kb), and bytes (b). For example:

maxBytes="50mb" or maxBytes="50000kb" or maxBytes="50000000b"

indicates that the log file size can grow to 50 megabytes before OpenDeploy closes that log file and starts a new one.

Ensure that you include the proper measurement indicator when you set the maxBytes attribute value. If no recognizable size measurement is indicated, OpenDeploy uses the default, bytes (b).

maxBackupIndex specifies the maximum number (1–9999) of archives that can be maintained for any OpenDeploy log. Default value is 9999. See “Maximum Archives Allowed” on page 252 for more information.

directory specifies the absolute directory location for the log files. The default location is: od-home/(od-instance)/log

You can only specify the log directory in the base server or receiver configuration. Unlike the other attributes, you cannot override this setting in a deployment configuration.

level indicates the level and type of logging OpenDeploy performs:

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.


• • • •••

Reports

Default Log Settings

The default base server logging configuration is: <logRules

maxBytes="32mb"

maxBackupIndex="100"

directory="od-home/log"

level="verbose"/>

which specifies the following:

The threshold size (32 MB) a log file can grow before it is rolled over and a new log file is opened.

100 archives that can be maintained for any OpenDeploy log

The log files (base server, receiver, deployment macro, and deployment micro) resides in the log subdirectory of the value you indicate for od-home.

The logging level is verbose.

You can change any of the values; they do not become effective until the server host restarts or the OpenDeploy services or daemons refresh.

The inclusion of the logRules element and its attributes and their values provide default logging settings for any deployment that does not specify logging settings in its own configuration.

ReportsOpenDeploy includes a reporting feature that can perform the following functions:

capture events

store event details

display reports in the browser-based user interface

allow for the integration of external reporting tools

The configuration file of each OpenDeploy base server or receiver includes the eventReporting element: <deployServerConfiguration>

...

<eventReporting

enabled="yes"

cfgPath="C:\Interwoven\OpenDeployNG\etc\eventReportingConfig.xml"/>


• • • •••


19


which specifies the server’s ability to use the reporting feature.

See “Reports” on page 281 for more information about the reporting feature.

EncryptionYour source server can encrypt deployed files using either of the following methods:

weak symmetric using key file-based encryption (40-bit)

strong asymmetric key encryption (up to 168-bit) using Secure Socket Layer-based (SSL) encryption

These types of encryption cannot be used with one another. Encryption settings are defined in the localNode element in the base server configuration file. See “Encryption” on page 258 for more information.

Deployment QueuesOpenDeploy allows you to line up, or queue, a second instance of the same deployment configuration to the server running the deployment. The OpenDeploy sending server only queues the last same-named deployment, replacing an existing same-named deployment that is already on the queue, but not currently running. This action protects against concurrency problems that would arise if multiple instances of a deployment were sent simultaneously. This feature is useful in an environment where incremental changes are pushed to production frequently and there is a risk that a deployment might be submitted while a previous deployment with the same name is still running.

NOTE



• • • •••

Specify the Completed Deployments List

Example

For example, if the OpenDeploy server mars started the deployment reports, and that same deployment was triggered again, perhaps by a different user, OpenDeploy queues this second instance of reports, and deploys it after the initial instance completes its run.

Deployment queuing is enabled in the initiatorProperties element residing in the base server configuration file (by default odbase.xml). Give the pendSessions attribute the value of yes. For example: <deployServerConfiguration>

...

<initiatorProperties pendSessions="yes" .../>

...


By default, deployment queuing is not enabled and the pendSessions attribute value is no. If deployment queuing is not enabled, any subsequent attempt to queue a deployment that is also currently running results in the immediate rejection or failure of the new deployment attempting to be initiated, however, the existing deployment that is already running is not affected.

Limitations

Deployment queuing does not work for deployments whose configurations are identical, but have different names. Deployment queuing can only apply to like-named deployments.

File list deployments can be queued, but OpenDeploy does not ensure that the files referenced in each instance are the same. Queuing deployments where the file list changes dynamically runs the risk of having a different set of files deployed between the first and second instance.

Deployment queuing does not consider parameter substitution in the deployment configuration. OpenDeploy queues deployments based on the same configuration using parameter substitution, even if the substituted values differ between deployments. Refer to the “Parameter Substitution” in the OpenDeploy Deployment Configuration Guide for more information on this feature.

Specify the Completed Deployments ListBy default, an OpenDeploy server lists the last 50 completed deployments each it has sent or received in the browser-based user interface (when the completed option is enabled), including multiple instances of the same deployment configuration. See “Monitor Deployments” on page 106 for more information.


• • • •••


19

You can specify another value for this list in the server’s base server or receiver configuration file. For base server, you can specify the number of sent and received deployments separately. For receivers, you can only specify the number of received deployments.

OpenDeploy supports a range of 1–100 completed deployments that can be displayed each for the sent and received deployments. Note that the higher the value, the more memory is required.

Completed Deployments Sent

You can adjust the number of displayed deployments sent by a base server in the initiatorProperties element’s completedQueueCapacity attribute of the server’s base server configuration file. For example: <deployServerConfiguration>

...

<initiatorProperties completedQueueCapacity="25" .../>

...


Specifying the value 25 results in the last 25 completed deployments sent by the server being listed in the Source Deployments window. The maximum value supported is 100. Default value is 50.

Completed Deployment Received

You can adjust the number of displayed deployment received by a base server or receiver in the listenerProperties element’s completedQueueCapacity attribute of the base server or receiver configuration file. For example: <deployServerConfiguration>

...

<listenerProperties completedQueueCapacity="75" .../>

...


Specifying the value 75 results in the last 75 completed deployments received by the server being listed in the Target Deployments window. The maximum value supported is 100. Default value is 50.


• • • •••

Validate Deployment Configuration Syntax

Validate Deployment Configuration SyntaxNOTE


You can require that any deployment configuration be validated against the associated DTDs before they run. If a deployment fails this validation, the deployment does not run and the errors are written to the log file hostname_odbase.log.

This feature is specified in the initiatorProperties element’s deploymentConfigValidation. attribute. To enable it, specify the value yes. For example: <deployServerConfiguration>

...

<initiatorProperties deploymentConfigValidation="yes" .../>

...


If the value is no (default), then the deployment runs without prior validation.

Serialize Transactional DeploymentsNOTE


You can configure OpenDeploy to perform transactional deployments in a serialized manner. This feature provides a safeguard against performance degradation and dead locks when doing concurrent fan-out transactional deployments with multiple deployments sharing the same target path (either full or fragment) in the receivers.

This feature only applies when in the deployment topology there is only one base server deploying to one or multiple receivers. If you have multiple base servers and multiple receivers involved in the deployments, use the pathRegistryChecking option at the receivers’ end together with serialization on the base server end. Unlike serialization of transactional deployments, which queues deployments at the sending side, concurrency management queues up deployments at the receivers’ end. See “Enable Concurrency Management” on page 179 for more information.

By default, serialization is turned-off in base servers. To turn on serialization of transactional deployments on the base server, specify the value of initiatorProperties element’s


• • • •••


20

serializeDeploymentSetUp attribute to yes in the of the base server configuration file (by default odbase.xml). For example: <deployServerConfiguration>

...

<initiatorProperties ... serializeDeploymentSetUp="yes" ...>

...

</initiatorProperties>

...


The default value is no.

You can serialize transactional deployments using either of the following methods:

Time-based is a strict order is maintained to ensure that deployments run in the same order in which they were kicked off.

Randomly: there is no ordering of deployments.

Set value of the serializeDeploymentSetUp attribute to yes if serialized transactional deployments are desired. For non-transactional deployments no serialization happens.

The type of serialization must also be included in the configuration, either serializeDeploymentByTime for time-based serialization or serializeDeploymentRandom for random serialization. Only one should be configured. If both are configured, only the first option is considered.

The following sections address each method’s configuration.

Time-based Serialization

Time-based serialization deployments are run in the same order in which they were kicked off.

To configure your serialization to be time based

add the serializeDeploymentByTime element under initiatorProperties

For example: <initiatorProperties ... serializeDeploymentSetUp="yes" .../>

<serializeDeploymentByTime

maxNumberOfDeploymentQueues="200"

maxDeploymentQueueLength="200"/>

</initiatorProperties/>

There can be only occurrence of the serializeDeploymentByTime element within the initiatorProperties element.


• • • •••

Specify Allowed Deploy and Run Scripts

The serializeDeploymentByTime element contains the following attributes:

maxNumberOfDeploymentQueues: Specify the maximum number of deployment queues that can be created by a sending OpenDeploy server inside the global registry hash. Any deployment causing this value to exceed this limit fails at the source. Default value is 100.

maxDeploymentQueueLength: Specify the maximum size of any deployment queue. Any deployment causing this value to exceed this limit fails at the source. Default value is 100.

Serialize Randomly

To serialize deployments randomly, there is no ordering of deployments.

To configure your serialization to be random

add the serializeDeploymentRandom element under initiatorProperties, for example: <initiatorProperties ... serializeDeploymentSetUp="yes" .../>

<serializeDeploymentRandom deploymentMaxWaitTime="10"/>

</initiatorProperties/>

There can be only occurrence of the serializeDeploymentByTime element within the initiatorProperties element.

The serializeDeploymentRandom element contains the following attribute:

deploymentMaxWaitTime: Specify the time (in seconds) that after which any deployment in waiting fails at the source server. A value of 0 indicates an infinite amount of time. Default value is 10.

Specify Allowed Deploy and Run ScriptsNOTE

This feature is only applicable to the base server.

You can specify which target-side Deploy and Run scripts can run on a specific target OpenDeploy server by configuring the allowedDnrs element in the target’s base server (by default odbase.xml) or receiver (by default odrcvr.xml) configuration file. The allowedDnr element resides within the dnrProperties element.

Within the allowedDnr element, you can specify one or more dnrCmd elements, each of which specifies a regular expression for its regex attribute value. OpenDeploy runs any Deploy and


• • • •••


20

Run script whose invocation string matches the regular expression specified by the dnrCmd element's regex attribute value. In the following example: <dnrProperties allowDnrExecution="yes">

<allowedDnrs>

<dnrCmd regex="yourscript"/>

<dnrCmd regex="^/usr/local/bin/scriptbin/"/>

</allowedDnrs>

</dnrProperties>

OpenDeploy can run any Deploy and Run script that has “yourscript” in its name, or any script residing in following location: /usr/local/bin/scriptbin/

Under this configuration, the following scripts run:

/bin/yourscript and

/usr/local/bin/scriptbin/foo.sh arg1 arg2

while the following script would not: /bin/foo.sh

Only target-side Deploy and Run scripts are checked by this feature. Source-side Deploy and Runs are not affected.

Inclusion of the allowedDnrs element is optional. If the allowedDnrs element is not specified in the configuration, all Deploy and Run invocations are allowed, unless explicitly disabled using the dnrProperties element. Refer to “Disable Deploy and Run Executions on the Target” for more information.

Installation of this service pack software does not automatically add the allowedDnrs element to the base server or receiver configuration files. You must manually add this element and then restart your service to enable this feature.

Specify Payload AdaptersNOTE


You can configure your base server to use payload adapters to generate a file manifest from the source file location. This file manifest is compared with the target file location and the appropriate files deploy.


• • • •••

Web Services

Payload adapters are defined in the payLoadProperties element in the base server configuration file. Refer to “Payload Adapter-Based Deployments” in the OpenDeploy Deployment Configuration Guide for more information.

Web ServicesContentServices for OpenDeploy is a SOAP-based interface that allows programmatic access to OpenDeploy base server or receiver functions. The language-neutral, firewall-friendly programming interface exposes Web services using industry-standard WSDL for starting and scheduling deployments, retrieving sender and receiver status, and administering OpenDeploy server changes. Refer to “Web Services” in the OpenDeploy Developer’s Guide for more information.

You must enable Web services on each OpenDeploy base server or receiver on which you want to use this feature. Web services are enabled in the webServices element. Specify yes for the enabled attribute value: <deployServerConfiguration>

...

<webServices enabled="yes">

...

</webServices>


The default value is no. If you specify no for the enabled attribute value or omit the attribute from the configuration, you cannot use Web services with the OpenDeploy server.

You must also specify one or both of the following transport protocols you use with Web services:

HTTP

HTTPS

The next two sections describe the configuration for each.

HTTP Transport

If you use HTTP as your transport protocol, you must specify and configure the httpTransport element within the webServices element: <webServices enabled="yes">

<httpTransport host="114.342.23.21" port="9273">


• • • •••


20

...

</httpTransport>

</webServices>

The httpTransport element contains the following attributes:

host: Specify the resolvable host name or IP address of the HTTP host. If your host has multiple IP addresses (with one or multiple network interface cards), you must specify an IP address rather than the host name.

port: Specify the port being used by HTTP.

HTTPS Transport

If you use HTTPS as your transport protocol, you must specify and configure the httpsTransport element within the webServices element: <webServices enabled="yes">

<httpsTransport host="114.342.23.21" port="9274" storePasswd="myStore"

certPasswd="abc123">

...

</httpsTransport>

</webServices>

The httpsTransport element contains the following attributes:

host: Specify the resolvable host name or IP address of the HTTPS host. If your host has multiple IP addresses (with one or multiple network interface cards), you must specify an IP address rather than the host name.

port: Specify the port being used by HTTPS.

storePasswd: Specify the password associated with the keystore.

certPasswd: Specify the password associated with the encryption certificate.

Using HTTPS with Web services requires additional OpenDeploy server configuration. See “Configure for HTTPS” on page 206 for more information.

Configure both HTTP and HTTPS on Hosts with Multiple IP Addresses

If your OpenDeploy server host has multiple IP addresses (with one or more multiple network interface cards), you can include a different httpTransport or httpsTransport element for each IP address, or even include a combination of both elements. For example:


• • • •••

Web Services

<webServices enabled="yes">

<httpTransport host="114.342.23.21" port="9273">

...

</httpTransport>

<httpsTransport host="114.342.23.22" port="9274">

...

</httpsTransport>

</webServices>

If you configure both HTTP and HTTPS on the same host, they must each use a different port number.

Using HTTPS with Web services requires additional OpenDeploy server configuration. See “Configure for HTTPS” on page 206 for more information.

Transport Connection Parameters

You can specify the webServiceTransport element within the httpTransport or httpsTranport elements. This element defines the transport connection parameters for the Web services. The webServiceTransport element contains the following attributes:

maxReadTime: Specify the maximum milliseconds that a read on a connection can block. Default value is 40000.

maxThreads: Specify the maximum number of serving threads allowed. Default value is 255.

minThreads: Specify the minimum number of waiting threads for a new incoming connection. Default value is 5.

maxIdleTime: Specify the maximum milliseconds a thread waits for a new connection. Default value is 2000.

In the following example: <webServices enabled="yes">

<httpTransport host="mars" port="9273">

<webServiceTransport

maxReadTime="60000"

maxThreads="100"

minThreads="2"

maxIdleTime="5000">

</httpTransport/>

</webServices>

The maximum time a read can be blocked is 60 seconds.

The maximum number of serving threads is 100.

The minimum number of waiting threads is 2.


• • • •••


20

The maximum idle time for a thread is 5 seconds.

Configure for HTTPS

You can use HTTP with Web services without additional configuration, but to use HTTPS transport with Web services, you must perform additional configuration.

To configure OpenDeploy to use HTTPS

1. Configure the webServices and httpsTransport elements in your OpenDeploy base server or receiver configuration file as is described in “HTTPS Transport” on page 204.

2. Determine the ContentServices Foundation (CSF) access service that the Web service clients uses and copy its shared passphrase key file, which resides in: csf-home/etc

3. Place the copied passphrase key file in the following location in your OpenDeploy server: od-home/etc

The name passphrase is the default name for this key file. You can give it another name, however, changing the file name requires that you update the Deploy.accessKeyFile attribute in the services configuration file (deploy.cfg) with the new name. See “Specify the Access Service Key File Usage and Name” on page 133 for more information on this procedure.

4. Ensure the required keystore file is present on the server, and contains the necessary certificates. See “Manage the Keystore File” on page 207 for more information on the keystore file.

5. Restart the OpenDeploy server to reflect these changes.

6. View the OpenDeploy server log to ensure that the server started successfully. This log resides in:

od-home/log/hostname_odbase.log or od-home/log/hostname_odrcvr.log

Messages are logged on which Web services transports started.

7. After the Web services start successfully, you can view the associated WSDL file from your browser using the following URLs:

http://http-hostname:http-port/iw/services/cd/1.2/opendeployservice

https://https-hostname:https-port/iw/services/cd/1.2/opendeployservice


• • • •••

Web Services

Manage the Keystore File

Using HTTPS in Web services requires a using keystore file that contains the certificate specified in the httpsTransport element in the OpenDeploy server configuration file. This keystore file must be named serverkeys, and must reside in: od-home/websvc/conf

You can use OpenDeploy command-line tools to perform the following keystore file-related tasks:

create a new certificate and places it in the keystore file

add an existing certificate residing in another location to the keystore file

export a certificate from the keystore file to the file certName.crt, which resides in the same location

display the list of the certificates currently maintained by the keystore file

NOTE

Performing any of these tasks on a UNIX host requires the user be root.

Create a New Certificate

You can create a new certificate using the iwodkeystorecreatecert command-line tool. Running this command creates the specified certificate specified and place it in the keystore file. If the serverkeys keystore file does not already exist, OpenDeploy creates it at the time the iwodkeystorecreatecert command runs.

To create a new certificate


2. Create the certificate by typing the following command at the prompt: iwodkeystorecreatecert -c cert -p password [-odinst instName]

where cert is the unique name of the certificate, and password is the password associated with the certificate.

Export an Existing Certificate

You can export a certificate current contained in your keystore file using the iwodkeystoreexportcert command-line tool. A certificate you export is not removed from the keystore file. Its contents are copied into a certificate file appending the certificate name with the .crt file extension, for example, myCert1.crt. Exported certificate files can be used to add


• • • •••


20

the certificate to another keystore file for use by the OpenDeploy Web services client or by a different OpenDeploy server.

To export an existing certificate


2. Export the certificate by typing the following command at the prompt: iwodkeystoreexportcert -c cert [-odinst instName]

where cert is the name of the certificate you are exporting.

Add an Existing Certificate

You can add an existing certificate from a file on the host file system to the serverkeys keystore file using the iwodkeystoreaddcert command-line tool. A certificate you want to add can be the product of an extraction from another OpenDeploy serverkeys keystore file or another source.

To add an existing certificate


2. Add the existing certificate by typing the following command at the prompt: iwodkeystoreaddcert -c certPath [-odinst instName]

where certPath is the full path the file containing the certificate, for example: iwodkeystoreaddcert -c C:\cert_files\extCert1.crt

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

For example, add a new certificate in the keystore by issuing:iwodkeystoreaddcert -c certName -f certPath

A new certificate from <certPath> is added with alias <certName> to the keystore file od-home/websvc/conf/serverkeys.

iwodkeystoreaddcert -h | -v

iwodkeystoreaddcert -c certName -f certPath [-odinst instName]



-c certName The alias of the certificate file to insert.

-f certPath The path of the certificate file to insert.

-odinst instName Use OpenDeploy instance, instName.


• • • •••

Database Deployments

Display the List of Certificates

You can display a list of the certificates contained in your OpenDeploy server’s serverkeys keystore file using the iwodkeystorelist command-line tool. You can use this command-line tool to verify that a certificate you attempted to created or added to the keystore file was successful.

To display a list of certificates


2. Add the certificate by typing the following command at the prompt: iwodkeystorelist [-odinst instName]

The list of certificates displays, for example: myCert1 myCert2 myCert3

Database DeploymentsOpenDeploy servers must be configured to perform the following types of database deployments:

database auto-synchronization (DAS) (base servers only)

standalone database deployments (base servers only)

target-side database deployments, including synchronized deployments of files and data assets

Target-side database and synchronized deployments require that the receiving server be configured for database deployments rather than the source server.

Database deployment functionality is specified in the databaseDeployment element: <deployServerConfiguration>

...

<databaseDeployment ...>

...

</databaseDeployment>

...


The databaseDeployment element contains the following attribute:


• • • •••


21

daemon_port: Specify the port to which the database deployment listener binds. You must replace the default value MYDATABASEDEPLOYPORT with a valid port number. The valid port range is 1–65535, with 1–1024 reserved for the operating system. This value must be a unique port number that is not in use by any other OpenDeploy instance or any other program.

use_storename_prefix: indicate whether (yes or no) to indicate if you use the current table naming convention. Specifying a value of no enables DAS to use table naming conventions defined in DataDeploy 5.2.x and prior versions only for the “default” store. For stores other than “default,” DAS uses the current table naming convention. Set this attribute only to migrate from DataDeploy 5.2.x and prior versions and to deploy to existing tables created by DataDeploy 5.2.x. Default value is no.

runmode: Specify one of the following values:

serialdaemon runs the deployments in a single-threaded mode. This setting is typically used for standalone database deployment operations.

threadperbranch runs the deployments from multiple TeamSite branches in parallel. This setting typically is used for DAS operations. This is the default value.

See “To determine the runmode” on page 211 for more information on this attribute and its values.

max_threads: (only use when the runmode is set to threadperbranch) specify a value for the maximum number of threads that DAS can create. Default value is 64.

Within the databaseDeployment element, you can specify one or both of the following child elements:

standalone defines the database deployment as being a standalone, which 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. For example: <databaseDeployment ...> <standalone .../> </databaseDeployment>

The standalone element contains the following attributes:

enabled indicates whether (yes or no) the ability to run standalone database deployments is enabled. Default value is no.

execProcess indicates whether (yes or no) OpenDeploy runs standalone database deployments in a child process rather than in a serialized thread in the OpenDeploy server. This feature is useful to run multiple database deployments in parallel, thereby achieving improved overall throughput. Default value is no.

das defines the database deployments as being Database Auto-synchronization (DAS), where TeamSite data content records (DCRs) or extended attributes (EAs) are automatically deployed to a database whenever a TeamSite data content records (DCRs) or a TeamSite area containing extended attributes is modified. For example:


• • • •••

Performance Throttle

<databaseDeployment ...>

<das.../>

</databaseDeployment>

The das element contains the following attribute:

enabled indicates whether (yes or no) the ability to run DAS deployments is enabled. Default value is no.

DAS requires additional configuration to operate. Refer to “Database Auto-Synchronization” in the Database Deployment for OpenDeploy Administration Guide for more information.

To determine the runmode

The value you specify for the runmode attribute depends on the types of deployments you want to run:

runmode=serialdaemon: When a base server is configured for database deployments in serial mode, deployments from different branches are queued up as a singular group.

runmode=threadperbranch: When a base server is configured for database deployments in thread-per-branch mode, deployments are queued on a per-branch basis.

Both options permit normal OpenDeploy deployments to run.

Performance ThrottleYou can configure your OpenDeploy server to cease sending (for base servers) or receiving (for base servers and receivers) deployments if certain performance factors are not met. This allows you to adjust or “throttle” your OpenDeploy environment to avoid overloading your sending and receiving servers.

You can configure the following performance factors on a given OpenDeploy server:

The number of deployment legs being sent or received simultaneously. A deployment leg is the movement of a specific set of deployed files from a source file location to a target file location.

The percentage of host disk space for the file system.

Throttle deployments are based on the virtual size of the OpenDeploy process.

You can configure these performance throttling factors within the thresholdProperties element: <deployServerConfiguration>

...

<thresholdProperties>


• • • •••


21

...

</thresholdProperties>


Within the thresholdProperties element are the following child elements:

disk contains one or more occurrences of the path element. The path element defines the minimum percentage of free host disk space required for an OpenDeploy server to send or receive deployments. The path element contains the following attributes:

name specifies the file system affected by the percentDiskFull attribute value. On a Windows host, the drive on which the area value resides is the affected disk. On a UNIX host, the file system containing the area value is the affected disk.

percentDiskFull specifies the maximum percentage full the file system can be to send or receive deployments.

deploymentLegs defines the maximum combined number of deployment legs permitted to be sent or received simultaneously by an OpenDeploy server. The deploymentLegs element contains the following attribute:

limit specifies the maximum number of deployment legs allowed to be sent or received by the OpenDeploy server.

virtualSize defines the virtual memory limit of OpenDeploy process beyond which any new deployment request is rejected. The virtualSize element contains the following attribute:

limit specifies the virtual memory threshold beyond which no new deployment requests can be sent or received by the OpenDeploy server.

In the following example, the mars has the following performance throttling configuration in its base server configuration file: <thresholdProperties>

<disk>

<path name="/dev" percentDiskFull="75"/>

</disk>

<deploymentLegs limit="10" />

<virtualSize limit="1gb" />

</thresholdProperties>

Before mars can send or receive deployments, the file system that contains the directory /dev must have at least 25 percent of its disk space free.

Additionally, it cannot send nor receive more than a combined total of 10 deployment legs simultaneously and still participate in any subsequent deployments. For example, if mars were performing a fan-out deployment to ten targets and it attempted to run another deployment, that deployment could not start because the deployment leg limit would be exceeded.


• • • •••

Hot Folder

Based on the configured virtual size threshold when new deployment request comes in to the OpenDeploy engine, OpenDeploy compares the threshold value with the current virtual size of the OpenDeploy process. If the current size exceeds the threshold size, new deployment cannot start.

Hot FolderHot folder is an OpenDeploy Base Server feature on the Windows platform where you can trigger deployments from configured hot folders without manual intervention upon the occurrence of a folder event such as:

adding a new folder or file to the folder

deleting a file

renaming or moving a file

changing the properties or contents of a file, and so on.

Deployments can be triggered in the following ways:

when a folder or file is added, deleted, or modified in the hot folder

at a configured interval, deployment is triggered capturing the cumulative changes into the filelist since the last hot deployment was triggered

The hot folder deployment configuration file, filelist is created in C:\WINDOWS\temp. It has the name pattern: hf_filelistXXX. A sample hot folder deployment configuration file is packaged with the OpenDeploy installation. It is in od-home\examples\conf-od\hotfolder_filelist.xml. It has two substitution parameters:

$area^ is the hot folder path as configured in odbase.xml. OpenDeploy substitutes this value at the time of triggering a deployment.

$filelist^ is the filelist path where OpenDeploy creates the filelist for the hot folder. OpenDeploy substitutes this value at the time of triggering a deployment.

To configure the hot file feature

1. Edit the odbase.xml file in od-home/etc.

2. Specify all the configured hot folders in the odbase.xml file. Configure paths as absolute paths to the folder.

Specify deploymentInterval in minutes when the deployment should trigger.

If the deploymentInterval parameter is not specified, deployment triggers instantly when the file changes are done in the configured hot folder.


• • • •••


21

If the deploymentInterval parameter is specified, the hot folder continues to write changes to a filelist file until the deploymentInterval minutes are reached, at which time the deployment triggers.

NOTE

Autonomy Interwoven recommends that you set the deploymentInterval value when you copy large folders or files. If this attribute is not used, there is a risk that a deployment may trigger while copying is in progress.

Example:<hotFolders deploymentInterval=”4”>

<folder hotFolderPath=”C:\Interwoven\OpenDeployNG\userLib” deploymentName=”hotfolder_filelist” />

<folder hotFolderPath=”…………” deploymentName=”…..” />

</hotFolders>

3. Save the odbase.xml file.

4. Restart the OpenDeploy Service.


• • • •••

Chapter 5

Scheduled Deployments

You can schedule a deployment to occur any time. You can schedule the deployment to run one time or recurrently based 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 do not interfere with other tasks. You can also schedule a deployment to take place with other events, such as a product announcement.

Any Administrator account can schedule any deployment on that OpenDeploy server. User accounts on an OpenDeploy server can schedule 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 with the command-line tools.


• • • •••

Chapter 5: Scheduled Deployments

21

Schedule from the User InterfaceYou can create, edit, delete, and view deployment schedules in the OpenDeploy user interface. Creating and editing schedules is performed in the New Schedule window (see Figure 45).

Figure 45 New Schedule window

New Schedule Window

The New Schedule window contains configurations for you to complete in scheduling a deployment configuration. Here you specify the time and date the deployment starts. 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 you assign to the scheduled deployment, the New Schedule window prompts you for additional scheduling information. You can also specify an end date when the schedule is no longer in effect.

Selected Server list: Select the name of the OpenDeploy server hosting the deployments for which you want to schedule.


• • • •••

Schedule from the User Interface

Deployment Group list: Select the group in which the deployment you want to schedule resides.

Deployment list: Select the name of the deployment you want to schedule.

Start Date lists: Select the date (month, date, and year) when you want the deployment to start.

Calendar button: Click to display the Calendar window, where you can select the date you want the deployment to occur. The date you select is automatically placed in the Start Date lists.

Start Time lists: Select the hour and minute on which you want the deployment to start.

Deployment Instance box: Type the instance name of the deployment.

Parameters box: Type the parameter=value pair. If you use more than one, separate each pair with a comma (,).

Description box: Type a comment of your choice to describe the deployment, such as “This deployment updates all product pages nightly.”

Deployment Frequency list: Select one of the choices for how often the scheduled deployment is to take place. Selecting any choice other than Once displays the End Date & Time section at the bottom of the window.

Once: Select if the deployment is non-recurring.

Sub-hourly: Select to enable deployments recurring in a fixed number of minutes. The Sub-Hourly section appears at the bottom on the window. Type 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. Type 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. Type 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. Type the interval in weeks between deployments in the Week Interval box. Select the day of the week the deployment is to occur from 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. Check each date that the monthly deployment is to occur. If you select a date that does not occur every month, for example “31”, that deployment does not occur until the next month that includes that date. A date of “31” skips June, and takes place in July.

Use End Date & Time check box: Select if you want to designate an end date for a recurring scheduled deployment. If clear this box, the recurring deployments take place indefinitely.


• • • •••


21

End Date lists: Select the month, date, and year on which you want the recurring deployment to end.

Calendar button: Click to display the Calendar window, where you can select the date you want the deployment to occur. The date you select is automatically placed in the End Date lists.

End Time lists: Select the hour and minute on which you want the recurring deployment to end.

Save button: Click to add the schedule you just made.

Cancel button: Click to cancel the scheduled deployment under development. The Deployment Schedules window opens.

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

Scheduled Deployments

To schedule a deployment

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 the deployment is to start from the Start Date lists. Alternatively, you can also click Calendar to display a calendar window. Select the date in this window to place it in the Start Date list.

5. Select the hour and minute you want the deployment to start from the Start Time lists. Use the 24-hour clock system, such as 13 to indicate 1 p.m.

6. (Optional) Type the deployment instance name in the Instance Name box. The value you type 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 “Schedule Deployment Instances” on page 227 for more information.


• • • •••


7. (Optional) Type the key/value parameter substitution value in the Parameters box. See “Apply Parameter Substitution to Scheduled Deployments” on page 226 for more information. Note that if your value contains spaces, do not enclose the parameter value in quotes, as is the case when specifying parameter substitution from the command line.

8. Type a description of the deployment in the Description box. For example: This deployment updates all product pages nightly.

9. Select one of the following options (see Figure 46) from the Deployment Frequency list:

Figure 46 New Schedules Frequency features

sub-hourly hourly daily

weekly

monthly

Once: Select if the deployment is not recurring.

Sub-hourly: Select to enable deployments recurring in a fixed number of minutes. The Sub-Hourly section appears at the bottom on the window. Type 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. Type 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. Type 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. Type the interval in weeks between deployments in the Week Interval box. Select the day of the week the deployment is to occur in the Day of the Week list.

Monthly: Select to enable deployments recurring every month on the same date. The Monthly section contains a 31 day calendar. Check each date that the monthly deployment is to occur. If you select a date that does not occur every month, for example “31,” then that deployment does not occur until the next month that includes that date. A date of “31” skips June, and takes place in July.


• • • •••


22

If you select 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 to designate an end date for the recurring deployments (see Figure 47). If you do not check this box, the recurring deployments take place indefinitely.

Figure 47 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 calendar window. Select the date in this window, and it is automatically placed in the End Date lists.

12. Select the hour and minute on which you want the recurring deployment to end from the End Time lists.

13. Click Save to complete the new schedule. The Deployment Schedules window opens (see Figure 48), displaying the new schedule you just created along with the other scheduled deployments.

Figure 48 Deployment Schedules window


• • • •••


View Schedules

Each time you add a schedule, that schedule displays in the Deployment Schedules window (see Figure 48 on page 220). You can also display all scheduled deployments for an OpenDeploy server by selecting view all from the Deployment list (see Figure 49).

Figure 49 Deployment Schedules window showing all scheduled deployments

View Scheduled Deployment Information

To view a deployment schedule

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.

If the configuration does not reside within a deployment group, but rather directly under the od-home/conf directory, select “/”. See “Organize Deployment Configurations” on page 96 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 appears for each listed deployment:

Name displays the name of the deployment. If you typed 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 the schedule was added. This may not be the same as the date when the first scheduled deployment occurs.


• • • •••


22

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

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

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

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 the scheduled deployment is active.

Edit Scheduled Deployments

To edit a scheduled deployment



3. Select the deployment whose scheduling information you want to edit from the Deployment list. That scheduled deployment displays.

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.

Delete Scheduled Deployments

To delete a scheduled deployment




• • • •••


3. Select the deployment whose scheduling information you want to edit from the Deployment list. That scheduled deployment is displayed.


4. Click Delete to remove the schedule from the scheduler database. You receive a prompt to confirm that you want to delete the schedule. If you confirm the deletion, that schedule is removed from the Deployment Schedules window.

Activate and Deactivate Scheduled Deployments

When you create a new schedule, it is activate and runs at its scheduled start date. You can stop the scheduled deployment, without deleting it, by deactivating it.

To deactivate a scheduled deployment





4. Click Hold to deactivate that deployment. The Active column displays no for that scheduled deployment, and the Hold button changes to Activate.

To reactivate a deactivated scheduled deployment





4. Click Activate to deactivate that deployment. The Active column displays yes for that scheduled deployment, and the Activate button changes to Hold.


• • • •••


22

Schedule from the Command LineYou can use the following OpenDeploy command-line tools (CLTs) to perform the associated scheduling-related tasks:

iwodcmd schedadd to add schedules to deployment configurations

iwodcmd schedget to view scheduling information on a selected deployment

iwodcmd scheddelete to delete existing schedules from deployment configurations

iwodcmd schedactivate to activate or deactivate a scheduled deployment

The scheduling CLTs only 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 117 for more information.

Add a Schedule

To add a schedule to a deployment from the command line


2. Add a schedule for a deployment by typing 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 list of these options with the usage syntax:

iwodcmd [-odinst instName] 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"]+



deployment Name of the deployment being scheduled.


• • • •••

Schedule from the Command Line

One-Time Only Deployments

If you only want to run the scheduled deployment once, you do not need to include any recurrence option. In the following example, to schedule the deployment reports to deploy a single time a week from now at the same time it is currently, type the following command at the prompt: iwodcmd schedadd reports -s 1w

Recurrent Deployments

To run your scheduled deployment indefinitely at the interval and time you specified, add the -r option and the time interval.

-r Repeat every N minutes, hours, days, or weeks.

-s [N][m|h|d|w] Time from current time to use as start date. The default is one minute from the typed command time.

-e [N][m|h|d|w] Amount of time from the current time to use as end date. The default end time is none; the scheduled deployment continues indefinitely.

n A numerical value.

m Minutes.

h Hours.

d Days.

w Weeks.

-c comment Description of the deployment being scheduled. See “Use of Comments” on page 226 for more information.

-inst instance Includes the deployment instance name instance, which is a suffix that is appended to the deployment name. This option is used to create unique deployment names for each instance of a deployment configuration.

-k key=value Specifies the key/value substitution. Note that the parameter iwdd is reserved when you are performing a deployment of a DataDeploy configuration. You may not use other parameter variables of the name iwdd.



• • • •••


22

You can also use the -s option and a time period to designate the time of day the deployment starts. Otherwise, the deployment starts at one minute past the time you type the command. In the following example, to schedule the deployment reports to run once a day starting at a time one hour from the time you are adding the schedule, type the following command at the prompt: iwodcmd schedadd reports -r 1d -s 1h

Recurrent Deployments with End Dates

You can specify an end date on which a recurring deployment ceases by including the -e option and the amount of time from now that the recurring deployment ceases. If you do not include an end date, the scheduled deployment occurs indefinitely.

In the following example, if you want the recurring scheduled deployment from the previous example to cease in two weeks, type 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 with the -c option. Your comment can be of any length and include spaces, however, if your comment includes spaces, you must enclose the 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 display with its corresponding scheduled deployment when you view deployments using the iwodcmd schedget command. This feature is equivalent to the Description box contained in the New Schedule and Edit Schedule windows in the OpenDeploy browser-based user interface.

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


• • • •••


To schedule the deployment to run a single time a week from now at the same time of day it is currently and apply the value C:\temp to the parameter srcarea, type 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, you must place the entire combined parameter and value inside of quotation marks. For example, if the value of srcarea is: C:\Program Files\monthly

type: iwodcmd schedadd reports -s 1w -k "srcarea=C:\Program Files\monthly"

Refer to “Parameter Substitution” in the OpenDeploy Deployment Configuration Guide for a complete description of the parameter substitution feature.

Schedule Deployment Instances

You can schedule an instance of a deployment using the -inst instance option with iwodcmd schedadd. Scheduling a deployment instance this way 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 “Specify a Deployment Instance” on page 115 for a description and usage of the deployment instance feature.

View Scheduled Deployment Information

You can access information on any schedule assigned to your deployment or all the schedules together, with 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 deployment schedules


2. Display the schedule information of a deployment by typing the following command at the prompt: iwodcmd [-odinst instName] schedget deployment options


• • • •••


22

where deployment is the name of the deployment.

There are various options associated with the iwodcmd schedget command-line tool. Here is a list of these options with the usage syntax:

To view all scheduled deployments on the OpenDeploy server

type the following command at the prompt: iwodcmd schedget -a

To view all schedules for the deployment reports

type the following command at the prompt: iwodcmd schedget -d reports

To view schedule information for the deployment reports with an ID number of “2”

type the following command at the prompt: iwodcmd schedget -o reports 2

iwodcmd [-odinst instName] schedget -h | -v

iwodcmd [-odinst instName] schedget -a

iwodcmd [-odinst instName] schedget -d deployment

iwodcmd [-odinst instName] schedget -o deployment -j ID



-a Gets all schedules. This is the default option.

-d deployment Gets all schedules for a given deployment.

-o deployment Gets one schedule. Requires the deployment name and the deployment ID number.

deployment The name of the deployment configuration.

-j ID Specifies a job. The ID number of the deployment. Each time a deployment runs, that deployment is given a unique ID number. Similarly, when you schedule a deployment, that scheduled deployment is also given a issued a unique ID number. Use the -a option to see all the ID number for your deployment.



• • • •••


Delete a Schedule

To delete a schedule from the command line


2. Delete a schedule from a deployment by typing the following command at the prompt: iwodcmd [-odinst instName] scheddelete deployment options


There are various options associated with the iwodcmd scheddelete command-line tool. Here is a list of these options with the usage syntax:

Because a deployment can have multiple schedules assigned to it, each schedule is issued a 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 “View Scheduled Deployment Information” on page 227 for more information.

iwodcmd [-odinst instName] scheddelete -h | -v

iwodcmd [-odinst instName] scheddelete deployment -j ID

iwodcmd [-odinst instName] scheddelete "dep_name_pattern*" [-j ID]




-j ID Specifies a job. The ID number of the deployment. Each time a deployment runs, that deployment is given a unique ID number. Similarly, when you schedule a deployment, that scheduled deployment is also given a issued a unique ID number. Use the iwodschedget -a command to see all the ID number for your deployment.

"dep_name_pattern*" Deletes schedules based on a wild card name selection, with an optional job identifying number (-j option). The wild card pattern must be quoted ("sample*"). If the optional job identifying number (-j option) is not present, all scheduled deployments beginning with "dep_name_pattern*" are 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 is deleted.



• • • •••


23

For example, to delete a schedule for the deployment reports with the ID of “5,” type the following command at the prompt: iwodcmd scheddelete reports 5

Activate and Deactivate a Schedule

When you create a new schedule, it is activate and runs at its scheduled start date. You can stop the scheduled deployment from occurring, without deleting it, by deactivating it.

To activate or deactivate a schedule from the command line


2. Activate or deactivate a scheduled deployment by typing the following command at the prompt: iwodcmd [-odinst instName] schedactivate deployment options


There are various options associated with the iwodcmd schedactivate command-line tool. Here is a list of these options with the usage syntax:

iwodcmd [-odinst instName] 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]



-a deployment Activates a specific scheduled deployment.

-a "dep_name_pattern*" Activates a scheduled deployment with an optional jobID (-j option) using a wild card pattern format. The wild card pattern must be quoted ("sample*"). If no -j option is present, all scheduled deployments beginning with dep_name_pattern change. 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 change.

-d deployment Deactivates a specific scheduled deployment, using the deployment and -j ID options.


• • • •••

Reactivate Schedules During or Past Their Effective Periods

To deactivate the scheduled deployment reports with an ID of “5”

type the following command at the prompt: iwodcmd schedactivate -d reports 5

Conversely, to reactivate the deployment, type the following command at the prompt: iwodcmd schedactivate -a reports 5

Reactivate Schedules During or Past Their Effective Periods

If a scheduled deployment is deactivated, either by selecting Hold in the browser-based user interface or by running the iwodcmd schedactivate command-line tool, reactivating it during or after the effective schedule period results in:

reactivation during effective period: After reactivating the schedule, all scheduled runs of the deployment that have already past are ignored. OpenDeploy runs the next scheduled occurrence of the deployment.

reactivation after effective period: OpenDeploy automatically deletes the scheduled deployment without running it.

See “Activate and Deactivate Scheduled Deployments” on page 223 for more information about activating and deactivating scheduled deployments using the browser-based user interface.

See “Activate and Deactivate a Schedule” on page 230 for more information on using the iwodcmd schedactivate command-line tool.

-d "dep_name_pattern*" Deactivates a scheduled deployment with an optional job identifying number (-j option), using a wild card format. The selection rules are the same as those stated in the schedule activation description.


-j ID Specifies a job. The ID number of the deployment. Each time a deployment runs, that deployment is given a unique ID number. Similarly, when you schedule a deployment, that scheduled deployment is also given a issued a unique ID number. Use the iwodschedget -a command to see all the ID number for your deployment.



• • • •••


23
• • • •••

Chapter 6

Logs

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, to determine whether they were successful, and for general troubleshooting.

Log File LocationThe 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 typing 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 “Configure Log Settings” on page 246 for more information.

Log File PermissionsOn UNIX hosts, OpenDeploy log files have the 644 permission (owner: read and write permission; group: only read permission; others: only read permission).


• • • •••

Chapter 6: Logs

23

View Log InformationYou can view log files using one of the following methods:

text editor

OpenDeploy user interface

View Log Files from a Text Editor

OpenDeploy log files are text files that can be opened with any standard text editor, including vi and Windows Notepad.

View Log Files from the OpenDeploy User Interface

You can view log files in the OpenDeploy user interface using the OpenDeploy Log Viewer window (see Figure 50). The OpenDeploy Log Viewer window is a separate browser window that opens when you click View Log in a window.

Figure 50 OpenDeploy Log Viewer window


• • • •••

OpenDeploy Log Viewer Window Contents

OpenDeploy Log Viewer Window ContentsThe OpenDeploy Log Viewer window contains logging information about the host or deployment.

Server displays the name of the OpenDeploy host 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 host log) or a deployment macro or micro log for a deployment sent or received.

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 for this deployment. 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.log indicates the log file is a receiver macro deployment log

src.deployment.server.log indicates the log file is a source micro deployment log

rcv.deployment.server.log indicates the log file is a receiver micro deployment log

<< 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: Type the number of lines of the deployment log you want to view. Type the exact number or click the arrows up or down in increments of 10 from the existing number. The range is size 10–1000 lines. You must click Refresh to implement the number you typed.

Position box: Type the proportional location percentage (0–100) of the log file to be displayed. You can type the exact number, or click the arrows up or down in increments of 10. For example, the beginning of the log is “0”, while the center is “50”. You must click Refresh to implement the number you typed.

Refresh button: Click to refresh the log with the Page Size and Position values you typed.

Each log you select to view displays in a separate browser window so you can view multiple logs simultaneously.


• • • •••

Chapter 6: Logs

23

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.

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


deployment is the name of the associated deployment.

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

source-server is the name of the source sending the deployment.

target-server is 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. Type the number of lines of the deployment log you want to view. You can type the exact number or click the arrows up or down in increments of 10 from the existing number. The range is 10–1000 lines. Click Refresh to implement the number you typed.


• • • •••

Base Server Logs

Position box: Type the proportional location percentage (0–100) of the log file to display. You can type the exact number or click the arrows up or down in increments of 10. For example, the beginning of the log is 0, while the center is 50. Click Refresh to implement the number you typed.

Refresh button: Click to refresh the log and to read in fresh data with the Page Size and Position values you typed.

Base Server LogsAll activities concerning the OpenDeploy base server are written to the base server log. Base server log entries include information on:

starting 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 a sample 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.


• • • •••

Chapter 6: Logs

23

By default, the base server log file resides in: od-home/(od-instance)/log/server_odbase.log

where server is the name of the base server. If your OpenDeploy base server is named mars, the base server log file path and name is: od-home/log/mars_odbase.log

To access the base server log from the user interface

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 opens displaying the OpenDeploy Log Viewer window containing the base server log (see Figure 51).

Figure 51 Base server log

Receiver LogsAll activities concerning an OpenDeploy receiver are written to the receiver log. Receiver log entries include information on:

starting OpenDeploy services and daemons


• • • •••

Macro Deployment Logs

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: od-home/(od-instance)/log/server_odrcvr.log

where server is the name of the receiver. If your OpenDeploy receiver is named venus, the receiver log file path and name is: od-home/log/venus_odrcvr.log

You can view the receiver log from the OpenDeploy user interface in the same manner as for the base server log. See “Base Server Logs” on page 237 for more information.

Macro Deployment LogsThe macro deployment logs write entries on every aspect of a deployment each time it runs. 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 has entries for each source/target pair. 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 deployments to each target succeeded

the time the deployments took

Reviewing the macro deployment log is a way to determine how a given deployment functions and to troubleshoot problems with that deployment. Here is a sample of macro deployment log: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]


• • • •••

Chapter 6: Logs

24

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: od-home/(od-instance)/log/src.deployment.log

where deployment is the name of the deployment configuration. If your deployment is named monthly, the source macro deployment log file path and name is: od-home/log/src.monthly.log

To access the source macro deployment log from the user interface

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 opens displaying the OpenDeploy Log Viewer window containing the source macro deployment log (see Figure 52).


• • • •••

Macro Deployment Logs

Figure 52 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 any time the combination of deployment name, definition name, and logical target name is unique. For example, if a deployment has three definitions pointing to the same target, three separate receiver macro log files are generated on the server that receives the deployment.

The receiver macro log by default resides in: od-home/(od-instance)/log/rcv.deployment.definition.target-server.log



definition is the name of the definition in the deployment configuration that contains the source/target pair.


• • • •••

Chapter 6: Logs

24

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

If your deployment is named monthly, the definition is named corporate, and the target’s logical name is jupiter, the receiver macro deployment log file path and name is: 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 240 for more information.

Micro Deployment LogsThe micro deployment logs write entries for each source/target pair in a deployment. If the deployment includes only a single source and target, one micro deployment log each generates on the source and targets. If the deployment is a fan-out type with several targets, a micro deployment log generates for each of those targets.

The source generates 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 run of the deployment results in a new set of log entries to be appended to the file, so you can review the history of the deployment over multiple runs.

Micro deployment log entries include information on:

contact made with the source or target

directories and files that successfully deployed

directories and files that failed to deploy

Reviewing the micro deployment log is a good way to determine how a given 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


• • • •••

Micro Deployment Logs

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 deployment to several targets, each source/target deployment logs its own micro deployment log.

The source micro log by default resides in: od-home/(od-instance)/log/src.deployment.definition.source-

server.to.target-server.log




source-server is the logical name of the source sending the deployment. If the logical name is not specified, the host name is used. The case sensitivity of the name is retained.

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

If your deployment is named monthly, the definition named corporate, your sending base server named mars, and the target named venus, the source micro deployment log file name is: src.monthly.corporate.mars.to.venus.log

If your fan-out deployment has the following targets:

venus

jupiter

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

To access the source micro deployment log from the user interface

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.


• • • •••

Chapter 6: Logs

24

5. Click View Log for the appropriate target. A separate browser window opens displaying the OpenDeploy Log Viewer window containing the source micro deployment log (see Figure 53).

Figure 53 Source Micro Deployment log

Receiver Micro Deployment Log

The receiver micro deployment log provides a similar service for OpenDeploy servers receiving deployments as the source micro deployment log does for sending base servers. The receiver micro deployment log contains entries about the movement of files between the source and targets during the deployment.

The receiver micro log by default resides in: od-home/(od-instance)/log/rcv.deployment.definition.source-server.

to.target-server.log

where,




• • • •••

Log Levels

source-server is the logical name of the source sending the deployment. If the logical name is not specified, the host name is used. The case sensitivity of the name is retained.

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

If your deployment is named monthly, the definition is named corporate, your sending base server is named mars, and the target is named venus, the receiver micro deployment log file name is: 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 243 for more information.

Log LevelsOpenDeploy provides the following log 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 “Configure Log Settings” on page 246 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 “Log Rules Hierarchy” on page 250 for more information.


• • • •••

Chapter 6: Logs

24

Define Log Levels in the User Interface

Any time you manually start a deployment from the OpenDeploy user interface (see Figure 54), you can specify the level of logging for that deployment. A level you specify here overrides any logging levels specified in the base server or deployment configurations.

Figure 54 Log Levels in the user interface

Define Log 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 “Run a Deployment from the User Interface” on page 99 for more information on using iwodcmd start to run deployments.

Configure Log SettingsOpenDeploy uses log4j to configure logging for OD, base server and receiver logs. You can configure logging for OD, base server and receiver logs in log4j.properties file. Individual deployment configurations (for example, test.xml), can be configured through base server and receiver configuration files (by default odbase.xml and odrcvr.xml). Defining the logging settings in the log4j.properties (for server logs) and configuration files (for deployment logs) automates the logging rules. In log4j.properties logging settings are defined in the log4 as FileAppender and in configuration files logging settings are defined in the logRules element.


• • • •••

Configure Log Settings

OD, Base Server, and Receiver Configurations

You can configure a log rotation policy based on SIZE and TIME for logfiles using log4j.properties file. OpenDeploy rolls over the log file based on either size or time specified in log4j.properties file. These values are specified as Appenders in log4j.properties file. The log4j attributes enables you to rotate the log files when it meets the configured appender's criteria based on either Size or Time by automatically generating a new log file.The location of log4j.properties file is: Interwoven/OpenDeployNG/etc

NOTE

You can also find a log4j.template file in the same location that can be used as a backup in case you inadvertently delete or modify log4j.properties file.

The following logfiles support log4j based log management.

od.log

<host_name>_odbase.log

<host_name>_odrcvr.log

Rotation based on Size

You can configure OpenDeploy to roll over a log file when file size exceeds its specified rollover size as indicated by its MaxFileSize attribute value in the log4j.properties file. Similarly you can specify the maximum number of archives that OpenDeploy has to maintain for size based rollover using MaxBackupIndex attribute value. The MaxFileSize and MaxBackupIndex attributes functions the same for od.log, <host_name>_odbase.log, and <host_name>_odrcvr.log

MaxFileSize specifies the maximum file size in bytes a log file is allowed to grow before the file closes and OpenDeploy begins writing to a new file. This value is called the rollover threshold. You can specify different byte measurements in the value, including megabytes (mb), kilobytes (kb), and bytes (b).

MaxBackupIndex specifies the maximum number (1–9999) of archives that can be maintained for any OpenDeploy log.

Example: Configuring a size based rotation policy for od.log log4j.appender.odLog=org.apache.log4j.RollingFileAppender

log4j.appender.odLog.MaxFileSize=5KB

log4j.appender.odLog.MaxBackupIndex=15

log4j.appender.odLog.File=${od.home}/od.log

log4j.appender.odLog.layout=org.apache.log4j.PatternLayout

log4j.appender.odLog.layout.ConversionPattern=%d{ABSOLUTE} %5p %c{1}:%L - %m%n


• • • •••

Chapter 6: Logs

24

In the previous example, a new od.log file generates every time the od.log file size exceeds 5 KB, however, after 15 log files, the log file that first rolled over is overwritten by the new one.

NOTE

Appenders are separate for od.log and <hostname>_odbase.log or <hostname>_odrcvr.log. odLog appenders correspond to od.log and serverLog appenders correspond to <hostname>_odbase.log or <hostname>_odrcvr.log.

Rotation based on Time

You can configure OpenDeploy to roll over a log file when the time exceeds its rollover schedule as indicated by its DatePattern attribute value in the log4j.properties file. If you configure the log file rotation to be time based, all the log files that are previously present and newly generated are retained unless you manually delete them.

Example: Configure a time-based rotation policy for od.log: log4j.appender.odLog=org.apache.log4j.DailyRollingFileAppender

log4j.appender.odLog.DatePattern='.'yyyy-MM-dd

log4j.appender.odLog.File=${od.home}/od.log

log4j.appender.odLog.layout=org.apache.log4j.PatternLayout

log4j.appender.odLog.layout.ConversionPattern=%d{ABSOLUTE} %5p %c{1}:%L - %m%n

In the example, the date pattern used is “'.'yyyy-MM-dd” and a new od.log file generates at midnight every day.

For more information on date patterns, refer to:http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/DailyRollingFileAppender.html

For more information on log4j logging services, refer to:http://logging.apache.org/log4j/1.2/index.html

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 neither the maxBackupIndex nor the directory attributes is present. For example: <logRules maxBytes="10mb" level="normal"/>

You can only specify an alternative log file home in the base server or receiver configuration file. Logging settings for macro and micro deployment logs in a deployment configuration overrides logging settings in the base server or receiver configuration.


• • • •••

Configure Log Settings

In the base server and receiver configuration file, the logRules element appears as: <logRules maxBytes="5Mb" maxBackupIndex="100" level="verbose"

directory="od-home/log"/>

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 closes and OpenDeploy begins to write a new file. This value called 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 closes that log file and starts 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 is specified: maxBytes="10"

OpenDeploy ignores the stated value and uses the default value (32mb) instead.

If the unit of measure is present, but unrecognized by OpenDeploy, it uses the default value. For example, if the following value is specified: maxBytes="1000x"

OpenDeploy ignores this value and uses the default value (32mb).

OpenDeploy does not honor a maxBytes value of less than 100 kilobytes (100kb). For example, if the following value is specified: maxBytes="50kb"

OpenDeploy ignores this value and uses the default value (32mb).

See “Log File Size Management” on page 250 for more information on rollover threshold.

maxBackupIndex specifies the maximum number (1–9999) of archives that can be maintained for any OpenDeploy log. Default value is 9999. See “Maximum Archives Allowed” on page 252 for more information.

level indicates the level and type of logging OpenDeploy performs.

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 the standard status and error messages. In most cases, this level of logging provides a sufficient amount of detail to meet your needs.


• • • •••

Chapter 6: Logs

25

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

Log Rules HierarchyThe following logging rules hierarchy apply to logging rules.

OD, Base Server, and Receiver Logs. The logging levels for the OD, base server, and receiver logs are specified in log4j.properties file. The level of logging is defined in the log4j.appender element.

Macro and Micro Deployment Logs. 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 uses its default logging settings. See “Configure Log Settings” on page 246 for more information.

If any syntax errors occur in the specified maximum bytes value, such as a unit of measurement being absent or unreadable, OpenDeploy uses its default values. See “Configure Log Settings” on page 246 for more information.

Log File Size ManagementLog 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 to determine the maximum size a single log file can grow before that file closes to new log entries and a new log file generates.

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 meets or exceeds its rollover threshold, the corresponding deployment macro log on the receiving server also rolls over, even


• • • •••

Log File Size Management

if it has not reached its rollover limit. The source base server determines when a rollover is required.

The deployment micro logs roll 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 roll over together. If a deployment is a fan-out type that includes multiple source/target pairs, the logs of each source/target pair roll over independent of other target-source pairs.

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 looks to the same element in the base server configuration file for logging information. If that information is not present, OpenDeploy uses the default size of 32 MB. See “Configure Log Settings” on page 246 for more information.

Rolled Over Log File Names

OpenDeploy rolls over a log file when it detects the file size exceeds its specified rollover size indicated by its maxBytes attribute value. A serial naming convention indicates 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 rolls over, that log’s file name is appended with a four-digit extension. This extension starts at 0001 and increases by one each time the same log rolls over. Each log has a separate counter to keep track the number of rollovers. OpenDeploy subsequently creates a new log file with the original log file name and starts writing log entries to it. For example, if the log file, src.monthly.log, reaches its rollover threshold level, OpenDeploy closes the file to further entries and subsequently archives 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)


• • • •••

Chapter 6: Logs

25

When the log rollover extension reaches the maxBackupIndex attribute value (see “Maximum Archives Allowed” on page 252), the next time it rolls the log over, it resets to 0001, followed by 0002, and so forth. If the log file with suffix 0001 already exists, that file is overwritten by the new one as the extension resets. If you want to preserve old log files that are at risk of being overwritten, move or copy them to another location.

Maximum Archives Allowed

You can specify the maximum number of archives that OpenDeploy maintains for the log files. Specify this number as the value for the maxBackupIndex attribute. For example: <... maxBackupIndex="5000" .../>

You can specify any value from 1–9999. Default value is 9999. If the maxBackupIndex attribute is not present in the configuration or if an allowed value is not given, the default value is used. See “Configure Log Settings” on page 246 for more information on configuring the logging rules.

Log File RecoveryThe 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 detects that it is missing and creates 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 runs.

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 restarts after having been stopped.


• • • •••

Log File Recovery

Log File Management

Log file management for adapters is similar to that of other OpenDeploy log files. The rollover threshold level and the maximum archive number is determined by the logging configuration in the OpenDeploy server file. See “Log File Size Management” on page 250 for more information.

The naming syntax for archived adapter log files differs from that of other log archives. For adapter logs, the naming is based on log4j's RollingFileAppender.

Deployment Log Files

OpenDeploy automatically generates 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.

Administration Server Logs

The administration server maintains the following log files.

hostname_database.log logs messages related to loading of drivers and connecting to the databases used for reporting and for database deployments.

hostname_subscriber.log logs subscriber errors and warnings for reporting.

hostname_adminServerReporting.log logs general status, warnings, and errors related to event reporting.

hostname_odadmin_servletd.log (Windows) or odadmin_servletd.log (UNIX) logs servletd status and errors.

odAdminServer.log logs debug messages for administration server.

localhost_log.YYYY_MM_DD.txt logs messages related to servletd startup and shutdown. A new log is created each day the adminserver is shutdown or started.

These logs reside in: admin-home/odadmin/log


• • • •••

Chapter 6: Logs

25

Reporting Logs

Several log files are associated with the OpenDeploy reporting feature. These log files, their locations, and configurations are described in “Reports” on page 281 under the following sections:

Server reporting log: see “Logs” on page 283.

Reporting logs associated with the administration server: see “Logs” on page 286.

Adapter Logs

Delivery and payload adapters used with OpenDeploy have their own log files. By default, these files reside in: 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 233 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 given leg of the deployment. See “Micro Deployment Logs” on page 242 for more information on how the legName value is composed.

Table 5 lists the adapter names used in the adapter log file naming.

Table 5 Adapter names used in the log file naming

Adapter Adapter Name

BEA bulk loader bbl

ClearCase cc

CVS cvs

Email email

Example delivery exmpld

FTP ftp

Generic delivery gen

Microsoft COM+ mscom

Microsoft Global Assembly Cache msgac

Microsoft Application Center msac


• • • •••

Log File Recovery

For example, the log file for the BEA bulk loader could be: 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 remain unchanged, however, following the upgrade, those adapters listed in the table starts generating new log files using the file naming syntax described here. legName.legacyAdapterName.log

Microsoft Visual Source Save (VSS) vss

Microsoft MSI msi

Microsoft IIS iisdel

MKS mks

PVCS pvcs

SQL sql

StarTeam starteam

WebLogic Application server wlas

WebSphere Application server wsas

WebSphere Portal target wspsd

WebSphere Portal source wspsp

Table 5 Adapter names used in the log file naming (Continued)

Adapter Adapter Name


• • • •••

Chapter 6: Logs

25
• • • •••

Chapter 7

Security

This chapter describes the OpenDeploy security features.

This chapter contains the following major topics:

Sender Node Authentication

Encryption

Non-root Operation

Multi-instance Support

Deploy and Run Restrictions

Command-Line Tools

Bootstrap Administrator

Administration Setup

strictAuthentication

Sender Node Authentication Allowed Hosts and Directories. See “Specify Allowed Hosts for Received Deployments” on

page 190 for more information about the Allowed Hosts & Directories security feature.

Strict Partner Checking. See “Host Checks during Deployments” on page 177 for more information about the Strict Partner Checking security feature.

Firewall Considerations. See “Deploy through a Firewall” on page 161 for more information about the Firewall Considerations security feature.


• • • •••

Chapter 7: Security

25

EncryptionOpenDeploy 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; they cannot be used 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 automatically overrides 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.

Configure OpenDeploy for Symmetric Encryption

Symmetric key encryption requires that the key file’s path be specified in the keyFile attribute of the localNode element in both the deployment configuration, and in the server configuration file of the receiving base server (by default odbase.xml) or receiver (by default odrcvr.xml). The base server configuration file of the sending server is not affected.

The keyFile attribute specifies the absolute path to the symmetric key. Here is an example of the OpenDeploy server mars being configured for symmetric key encryption: <localNode host="mars" keyFile="/local/OpenDeploy/conf/keyfile.txt"/>


• • • •••

Encryption

Use Symmetric Encryption with Reverse Deployments

If you perform 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 location specified in the base server or receiver configuration file of the reverse source. This differs from a forward deployment, where the configuration includes 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 runs on UNIX. The target venus has the receiver software installed and runs on Windows. In a typical forward deployment using symmetric key encryption, the localNode element in the deployment configuration residing on mars is: <localNode host="mars" keyFile="/local/OpenDeploy/conf/keyfile.txt"/>

and the localNode element in venus’ receiver configuration file is: <localNode host="venus" keyFile="C:\encryption\keyfile.txt"/>

In a reverse deployment involving these two servers, the localNode element in the reverse deployment configuration is: <localNode host="mars" keyFile="C:\encryption\keyfile.txt"/>

and the localNode element in the base server configuration file on mars is: <localNode host="mars" keyFile="/local/OpenDeploy/conf/keyfile.txt"/>

Secure Data Transfer with SSL

OpenDeploy uses X509.v3 digital certificates and Secure Socket Layer (SSL) version 3 for secure content transfer. OpenDeploy comes 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.

OpenDeploy supports DSA and RSA certificates; they have only been tested using the certificate authority that comes packaged with OpenDeploy. Certificates that require a password do not work with OpenDeploy.

The use of 168-bit encryption is available in the United States and most other countries. You can also set up OpenDeploy to accept multiple levels of encryption.

The following sections describe the process of creating digital certificates. This is a multi-step process that requires familiarizing yourself with the complete process before you begin any individual tasks. You should read this chapter completely before attempting this process.


• • • •••

Chapter 7: Security

26

Obtain 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, refer to a cryptography reference manual such as Applied Cryptography (Bruce Schneier, ISBN 0-471-11709-9).

Set up 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

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 which level of encryption you use. Either the source or target has the ability to request a verification of the certificate authority before the deployment can occur. See “Configure OpenDeploy for SSL Data Transfer Encryption” on page 269 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: od-home/bin.


• • • •••

Encryption

Table 6 lists the files used for generating the certificate authority.

The openssl.exe and openssl programs are command-line tools for using the various cryptography functions of OpenSSL's cryptography library from the shell. See “Obtain Additional SSL Information” on page 260 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 used to create the certificate authority and to generate the certificates and private keys for OpenDeploy.

By default, the database is in the directory where the programs are run. If future public and private key pairs are created using a different certificate authority, OpenDeploy cannot 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 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 if the current authority is overwritten, OpenDeploy cannot deploy files using these certificates.

Set up the Certificate Authority

To set up the OpenSSL certificate authority

1. Verify that the od-home/bin directory is included in the PATH environment variable.

UNIX: Type env|grep PATH at the prompt.

Windows: Right-click My Computer and select Properties from the shortcut menu to open the System Properties window. Then, select the Advanced tab. Finally, click Environment Variables. to open the Environmental Variables window. The current path in use is displayed in the System variables list.


3. Make a backup copy of openssl.cnf file, for example openssl.cnf_orig.

4. Open the openssl.cnf file with a text editor.

5. Change the following line if you want the certificate to last for longer than a year. default_days =365 # how long to certify for

Table 6 Files for generating the certificate authority

Windows UNIX

openssl.exe openssl

openssl.cnf openssl.cnf

CA.bat CA.sh


• • • •••

Chapter 7: Security

26

6. Change the default values for your installation. These are located in the [ req_distinguished_name ] section of the file.

7. Ensure that the RANDFILE variable in openssl.cnf is set to: RANDFILE=.rnd

When invoking the OpenSSL utilities, run them in od-home/bin, which is where the openssl.cnf file also resides.


9. Create a seed file (*.rnd) for the random number generator by performing the following steps:

a. Type the following command at the prompt: netstat -a > .rnd

b. Move this .rnd file to: od-home/bin

Alternatively, you can copy any file sufficiently large into a .rnd file to make it a seed file. Log files are a good example of random data for seeding. The key requirement is that the data used for seeding is either 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 random data so it does not generate predictable keys.

“Obtain Additional SSL Information” on page 260 for more information on seeding methods.

10. Create the new certificate authority by typing the following command at the prompt:

Windows: CA.bat -newca

UNIX: CA.sh -newca (press Enter at the prompt to create the new certificate authority.)

By default, the certificate authority has a life span of 365 days. 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 263 for more information.

If the certificate authority already exists, the script prints harmless error messages about existing directories and finishes execution.

Creating the certificate authority results in the following directory being created and copies the authority's certificate/key pair into it. od-home/bin/demoCA

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


• • • •••

Encryption

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 type other information. The prompts for organization name, organizational unit name, common name, and e-mail address are optional. You can either type a value or leave them blank by typing the value “.”. All of the inputs to the prompts constitute the Distinguished Name.

The more unique values you provide for the optional prompts, the more effective the certificate authority is. Each certificate authority you create must be unique from all other certificates. One method to ensure disparate Distinguished Names is by providing dissimilar values for the Common Name prompt.

You can begin the certificate authority process by deleting the directory containing the certificates. There is no penalty for this until you begin issuing certificates. You cannot use certificates that have the same Distinguished Name as the certificate authority. You invalidate all certificates signed by a 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, to specify a certificate authority expiration date of 200 days after creation, type one of the following commands at the prompt:

Windows: CA.bat -newca -days 200

UNIX: CA.sh -newca -days 200

The expiration date of the generated certificate is specified in the openssl.cnf file. If the expiration date of the certificate does not match the certificate authority you specified with the -days option, OpenDeploy assigns the shorter expiration date of certificates generated from the authority. See “Certificate Expiration” on page 265 for more information.


• • • •••

Chapter 7: Security

26

Generate a Certificate

Creating a certificate is 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. 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 include in SSL deployments.

To generate a certificate for an OpenDeploy server

1. Navigate to the od-home/bin directory.

2. Generate a new certificate and key by typing the following command at the prompt:

Windows: CA.bat -certall

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.

3. Type 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 exactly the 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.


• • • •••

Encryption

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. Also rename the certificate and key to reflect their roles in the deployment cycle because newly generated certificate/key pairs overwrites 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, physically transport them on a tape or diskette. Since you also have to move the certificates to the target, you may choose to compress and package these items into a .tar or .zip file before you transfer them to peer servers.

Certificate Expiration

The life span of the generated certificate is specified by the default_days attribute in the openssl.cnf file. This number is the expiration days for certificates newcert.pem generated based on cacert.pem. The default expiration period is 365 days.

If the expiration date of the certificate does not match the certificate authority you specified using the -days option, OpenDeploy assigns the shorter expiration date to certificates generated from the authority. In some cases, you may 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 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 certificate authority

1. Generate a certificate signing request CSR/private key pair using the following command:

Windows: CA.bat -newreq

UNIX: CA.sh -newreq


• • • •••

Chapter 7: Security

26

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-----" (include those lines). Use the third-party’s approved method to send them the CSR, such as in an e-mail message or through a Web form.

If the CA requires the CSR to 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 e-mail message and send it to the third-party CA.

Upon receiving the CSR, the third-party CA subsequently returns the signed certificate and the CA’s own certificate.

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 they are by copying and pasting them into the files newcert.pem and cacert.pem.

If the returned certificates are in DER format, you must convert them to PEM format by running the following command at the prompt: openssl x509 -in CA_file.der -inform DER -out CA_file.pem

-outform PEM

where CA_file represents the names of the new certificate or CA certificate file as appropriate.

4. Update the localNode element in base server, receiver, and deployment configuration files as necessary to reference to your signed certificate, your private key, and the third-party CA's certificate. For example: <localNode

host="mars"

sslCertificate="path_to_third-party_signed_certificate"

sslPrivateKey="path_to_local_generated_key (ex. newreq.pem from

step 1)"

sslCaCertificate="path_to_third-party_CA_certificate"

...>


• • • •••

Encryption

Change OpenSSL Defaults

Much of the process for generating certificates has been automated and much of the input to the automation can be defaulted. The defaults are specified in the configuration file: od-home/bin/openssl.cnf.

For example, if 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 “Obtain Additional SSL Information” on page 260 for more information on modifying openssl.cnf.

SSL Configuration and Deployment Errors

Errors can occur when creating certificates or while setting up the deployments. Two of the most commonly reported error messages are: PRNG not seeded

Unable to write 'random state'

These messages indicate that you have not seeded the random number generator with enough data. See “Set up the Certificate Authority” on page 261 for more information about seeding the random number generator.

If the following error message displays, it indicates that both the certificate and the certificate authority have the same name. Self-signed certificate

You 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. Then you can regenerate the certificate and ensure that you are not reusing all of the certificate authority's name. See “Obtain Additional SSL Information” on page 260 for more information about errors.

Verify Certificates

You can verify the validity of the certificates you generate by typing the following command at the prompt:

Windows: CA.bat -verify


• • • •••

Chapter 7: Security

26

UNIX: CA.sh -verify

If you 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

CA.sh –verify odtgtcert.pem

If the certificate is valid, the following message displays: certificate_name.pem: OK

For example, if you type the following: CA.bat -verify newcert.pem

the following message displays: newcert.pem: OK

However, if there is a problem, OpenDeploy displays an error message such as: 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 result from not using a unique Common Name when generating the certificates. See “Generate a Certificate” on page 264 for more information.

Use 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 either 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 the most control over which senders are 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.

A typical concatenated CA certificate is as follows:-----BEGIN RSA PRIVATE KEY-----

<Key1 content>


• • • •••

Encryption

-----END RSA PRIVATE KEY-----

-----BEGIN CERTIFICATE REQUEST-----

<Key2 content>

-----END CERTIFICATE REQUEST-----

Note that the CA certificate file is generated by manually copying contents from multiple certificate files “as it is” into one.

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 must only 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 methods to create a group structure among the sending servers. Each server can belong to one of several groups and target servers can have the certificates of the CAs of the groups they want to allow connections from. For example, have one CA for servers in each geographical region of an enterprise. Target servers in a given region can have in their CA list the CA from their own region, but target server corporate headquarters all of them.

Configure 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 else the encryption fails.

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, all incoming deployments are expected to be encrypted this way.

Encryption values in the deployment configuration are also specified in the localNode element and the same attributes apply. Encryption in the deployment files only apply to that deployment.

In both cases, you must have the following attributes and their values specified within the localNode element:

sslCertificate: Type the absolute path to the SSL public key certificate.


• • • •••

Chapter 7: Security

27

sslPrivateKey: Type the absolute path to the SSL private key certificate.

sslCaCertificate: Type 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) indicates which of the following conditions apply in regard 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.

Here is an example of how the localNode element and its encryption-related attributes can be configured for SSL data transfer encryption in the base server configuration file or in a deployment configuration: <localNode

host="mars"

sslCertificate="od-home/cert/odsrccert.pem"

sslPrivateKey="od-home/cert/odsrckey.pem"

sslCaCertificate="od-home/bin/demoCA/certs/cacert.pem"

sslVerifyPeer="request"/>

Here is an example of how the localNode element and its encryption-related attributes can be configured for SSL data transfer encryption in the target receiver configuration file: <localNode

host="venus"

sslCertificate="od-home/cert/odtgtcert.pem"

sslPrivateKey="od-home/cert/odtgtkey.pem"


sslVerifyPeer="request"/>

Ciphers

You can specify various ciphers to use in encryption. During a connection, the OpenDeploy source and targets negotiate 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"


• • • •••

Encryption

where cipherlist contains one or more ciphers, ranked left to right from highest priority to lowest priority, separated by colons (“:”). For example: sslCiphers="EDH-RSA-DES-CBC3-SHA:DES-CBC-SHA"

The following is a list of all cipher strings and their meanings:

DH: cipher suites that use DH, including anonymous DH.

ADH: anonymous DH cipher suites.

3DES: cipher suites that use triple Data Encryption Standard.

DES: cipher suites that use Data Encryption Standard (not triple DES).

RC4: cipher suites that use RC4.

RC2: cipher suites that use RC2.

IDEA: cipher suites that use IDEA.

MD5: cipher suites that use MD5.

SHA1, SHA: cipher suites that use SHA1.

Refer to the following Web site for more information on ciphers: www.openssl.org/docs/apps/ciphers.html

OpenDeploy allows you to use the following types of cipher:

No-authentication ciphers: None.

Low-strength (56 and 40 bit) ciphers:

EXP1024-RC4-SHA (56 bit)

EXP1024-DES-CBC-SHA (56 bit)

EXP1024-RC2-CBC-MD5 (56 bit)

EXP1024-RC4-MD5 (56 bit)

EDH-RSA-DES-CBC-SHA (56 bit)

DES-CBC-SHA (56 bit)

EXP-EDH-RSA-DES-CBC-SHA (40 bit)

Medium-strength (128 bit) ciphers: RC4-SHA

RC4-MD5 SSLversion 2 or version 3

High-strength (168 bit) ciphers: EDH-RSA-DES-CBC3-SHA

DES-CBC3-SHA


• • • •••

Chapter 7: Security

27

If sslCiphers is not specified, OpenDeploy tries each supported cipher, starting from high-strength, until a compatible cipher is found with the remote OpenDeploy server. If no compatible is found, the deployment fails.

The following example adds a 168-bit cipher and a low-strength cipher to the SSL data transfer key encryption code created in “Configure OpenDeploy for SSL Data Transfer Encryption” on page 269: <localNode

host="mars"




sslVerifyPeer="request"

sslCiphers="EDH-RSA-DES-CBC3-SHA:DES-CBC-SHA"/>

Test the SSL Encryption Configuration

After you configure OpenDeploy for SSL encryption, you should test it before performing a 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, 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

1. Navigate to: 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: <localNode

host="host_name"






4. Navigate to: od-home/(od-instance)/etc

5. Modify the localNode element in the base server configuration file (by default odbase.xml) as follows: <localNode

host="host_name"

sslCertificate="od-home/cert/odtgtcert.pem"

sslPrivateKey="od-home/cert/odtgtkey.pem"


• • • •••

Encryption




If testssl.xml is configured to deploy to other servers as well, each target’s server configuration file must be modified in this way.

6. Stop and restart the OpenDeploy service or daemon on each server whose base server or receiver configuration file you modified in the previous step. See “Stop OpenDeploy” on page 49 and “Start OpenDeploy” on page 45 for more information.

7. 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 “Logs” on page 233 for more information.

Logs

You can verify that a deployment ran with SSL encryption by viewing the receiver micro deployment log file. An entry that indicates 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 244 for more information on this type of log file.

Support for Third-Party Certificate Authority with SSL Encryption

You can use 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 certificate authority with SSL encryption

1. Generate a certificate signing request CSR/private key pair using the following command:

Windows: CA.bat -newreq

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.


• • • •••

Chapter 7: Security

27

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 e-mail 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 e-mail message and send it to the third-party CA.

Upon receiving the CSR, the third-party CA subsequently returns the signed certificate and the CA’s own certificate.

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 they are by copying and pasting them into the files newcert.pem and cacert.pem.

If the returned certificates are in DER format, you must convert them to PEM format by running the following command at the prompt: openssl x509 -in CA_file.der -inform DER -out CA_file.pem -outform PEM

where CA_file represents the names of the new certificate or CA certificate file as appropriate.

4. Update the localNode element in base server, receiver, and deployment configuration files as necessary to reference to your signed certificate, your private key, and the third-party CA's certificate. For example: <localNode

host="mars"

sslCertificate="path_to_third-party_signed_certificate"

sslPrivateKey="path_to_local_generated_key (ex. newreq.pem from

step 1)"

sslCaCertificate="path_to_third-party_CA_certificate"

...>


• • • •••

Non-root Operation

Non-root Operation See “Run OpenDeploy on UNIX as Non-Root” on page 61 for more information about the non-root operation security feature.

Multi-instance Support See “Run Multiple Instances of OpenDeploy” on page 52 for more information about the Multi-instance Support security feature.

Deploy and Run Restrictions See “Enable Target-Side Deploy and Run” on page 185 for more information about the Deploy-and-Run Restrictions security feature.

Command-Line ToolsSee “Run Deployments from the Command Line” on page 113 for more information about the Command-Line Tools feature.

Bootstrap AdministratorSee “Specify the Bootstrap Administrator User Name” on page 132 for more information about the Bootstrap administrator security feature.


• • • •••

Chapter 7: Security

27

Administration SetupSee “Roles and Authorization” on page 117 for more information about the Administration Setup security feature.

strictAuthenticationSee “Restrict Access to Users with OpenDeploy Roles” on page 182 for more information about the strictAuthentication security feature.

allowedEventReportingHost

allowedEventReportingHost is a fully Qualified Domain Name of the allowed host which is running event reporting component, such as, hostName.myDomain.com. This feature is applicable only when 'strictAuthentication' is set to 'yes' (refer to element <listenerProperties>). This is a Security feature to allow event polling; only from a valid event reporting host and for a given OpenDeploy Base Server/Receiver there can be only one such event reporting host.

Decode Requests to OpenDeploy Server Treated as Decryption

This feature is applicable only when strictAuthentication is set to yes (refer to element <listenerProperties>). All password decoding requests to OpenDeploy Server are treated as decryption. The passwords are encrypted using iwodpassencrypter CLT and then saved in the respective configuration file, which is decrypted by OpenDeploy server.

The iwodpassencrypter CLT is available in both OpenDeploy Base server and Receiver and resides in: <od-home>/bin

Secure RMI

The secure RMI feature overcomes a security vulnerability through the RMI port.

The OpenDeploy Server has an RMI interface that is used by the OpenDeploy RMI client applications such as OpenDeploy Admin UI, ControlHub Admin UI, Admin Console UI,


• • • •••


OpenDeploy SNMP Agent, OpenDeploy Command Line Tools, OpenDeploy API Test code, OpenDeploy Event Reporting Component, CH workflow deploy task, and custom clients.

The OpenDeploy Admin/CH Admin/Admin Console/Workflow deploy task invokes RMI calls with user context information of the logged-in OpenDeploy user. For rest of the RMI clients, OpenDeploy implicitly uses encoded usernames or by passes the authentication checks if the RMI request is from the server host itself.

The impact of the RMI vulnerability is that clients that did not pass through the context string check were potential threats as client authentication happened for these clients, which made the OpenDeploy Server vulnerable to malicious clients.

Therefore, a malicious client could pose to the server as if it were connecting from the local host where the OpenDeploy Server runs. As the server bypasses some authentication checks for local client requests, it becomes vulnerable to malicious client attacks.

The Secure RMI feature reinforces security for client applications that do not have strong user authentication with just Strict Authentication enabled. The Secure RMI feature is an add-on to Strict Authentication and can be enabled only when Strict Authentication is enabled.

All releases of OpenDeploy prior to version 7.2.0 are affected by the RMI security vulnerability. All such vulnerabilities are addressed and resolved by the OpenDeploy Secure RMI feature.

With the secure RMI feature, both the client-side and server-side take a shared secret approach to encrypting and decrypting the user ID and password to authenticate RMI requests. The customer needs to configure an encrypted client password for each OpenDeploy RMI client type on the OpenDeploy server and share these encrypted passwords with the OpenDeploy clients. The OpenDeploy Server can trust an OpenDeploy RMI client only if the client invokes an RMI call with the same encrypted password.

OpenDeploy Server Configurations for Secure RMI

To enable Secure RMI on the OpenDeploy server

1. Edit the OpenDeploy server configuration file, odbase.xml or odrcvr.xml.

2. Enable strictAuthentication in the listenerProperties element.

3. Add new XML element secureRMI to deployServerConfiguration with attribute enabled and value yes.

Example:<deployServerConfiguration>

<listenerProperties name=”InterwovenOpenDeploy” bindPort=”20014” strictAuthentication=”yes” />

...

<secureRMI enabled=”yes”/>


• • • •••

Chapter 7: Security

27

...


Strict Authentication must be enabled for the OpenDeploy Secure RMI feature to work.

By default, secure RMI feature is disabled. If you want to run OpenDeploy Server in the secure RMI mode, you must make the preceding configuration changes.

To configure client-type passwords on the OpenDeploy server

1. Predefine keys for each client type:

APP_ODRMICLT: Entry is relevant to all OOTB OpenDeploy Command Line Tools (CLT).

APP_ODRMISNMP: Entry is relevant to the co-located OpenDeploy SNMP server.

APP_ODAPITEST: For API testing purposes.

APP_ODEVENTREPORT: For the OpenDeploy Event reporting module that is part of OpenDeploy Admin/CH Admin/Admin Console.

APP_CUSTOM: For any custom RMI client.

2. Encrypt the passwords for each client type using the OOTB OpenDeploy CLT: od-home/bin/iwodpassencrypter.

i. To configure the encrypted password on the default initial OpenDeploy instance (except for client type APP_ODEVENTREPORT), use:

<od-home>/bin/iwodpassencrypter <yourPasswordStringToEncrypt>

ii. To configure the encrypted password on any other OpenDeploy instance (except for client type APP_ODEVENTREPORT), use:

<od-home>/bin/iwodpassencrypter -odinst <od-instance-name> <yourPasswordStringToEncrypt>

iii. For the Event Reporting client (that is, APP_ODEVENTREPORT), encrypt the client-type password with the access key file (that is, od-home/etc/passphrase) that is already configured for the pair of OpenDeploy Server and the Event Reporting module for Strict Authentication.

<od-home>/bin/iwodpassencrypter -p <od-home>/etc/passphrase <yourPasswordStringToEncrypt>

3. Create a clientApplicationConfig.properties file in <od-home>/etc.

4. Edit the properties file and add client-type key and encrypted password pairs. An example template file is provided at: od-home/etc/clientApplicationConfig.properties.template.

5. Save the properties file.

6. Restart the OpenDeploy Server.


• • • •••


Additional OpenDeploy Instance Configuration for Secure RMI

Each OpenDeploy server instance needs to be configured independently and set up to run in a secure RMI mode. The configurations are similar to the default OpenDeploy server configuration.

To configure additional OpenDeploy instances for secure RMI

1. Edit the OpenDeploy server configuration file, odbase.xml or odrcvr.xml at <od-home>/inst/<INSTANCE-NAME>/etc.

2. Set strictAuthentication=”yes” and <secureRMI enabled=”yes”/>.

3. Save the xml file.

4. Edit <od-home>/inst/<INSTANCE-NAME>/etc/clientApplicationConfig.properties.

5. Set up the client-type encrypted passwords by following step 2 of the previous procedure

6. Save the properties file.

7. Restart the OpenDeploy server instance.

OpenDeploy Client Configurations and Enhancements for Secure RMI

Any OpenDeploy RMI client that is to communicate with an OpenDeploy server running in secure RMI mode should have access to the encrypted password set up on the server for its client type. Further, the client needs to pass along the encrypted password and the current user ID while making a RMI call.

Configuration

Configure the client to have access to a clientApplicationConfig.properties file that contains the encrypted form of the client-type password that is also configured on the OpenDeploy server instance to which it would make RMI calls.

For the OpenDeploy server co-located RMI clients with keys APP_ODRMICLT, APP_ODRMISNMP and APP_ODAPITEST, there is no need for explicit configuration as they can access the passwords from the local clientApplicationConfig.properties file configured for the OpenDeploy server.

For remote RMI clients such as Event Reporting components with key APP_ODEVENTREPORT, the clientApplicationConfig.properties file with the encrypted passwords must be explicitly configured or copied from the OpenDeploy server at a predefined location accessible by the Event Reporting component. The Event Reporting component is part of OpenDeploy Admin, ControlHub, and Admin Console. The predefined locations for the password properties file in each are:


• • • •••

Chapter 7: Security

28

OpenDeploy Admin: <IW-HOME>/AdminServer/odadmin/config

ControlHub: <IW-HOME>/ControlHub/odadmin/controlhub

Admin Console: <IW-HOME>/ApplicationContainer/config/odadmin/config

Implementation

For any custom RMI client with the key APP_CUSTOM, the following implementation aspects need to be taken care of while invoking RMI calls on a OpenDeploy server running in secure RMI-enabled mode.

To implement a custom RMI client

1. To the user object (IWUser) created to pass with the RMI call should set the client type key. userobject.setClntApp(“<CLIENT_TYPE_KEY>”)

2. The client has to set the path to the clientApplicationConfig.properties file in the user object:

userobject.setClientCfgPath(“<absoulte_path_to_clientApplicationConfig.properties_file>”)

As of version 7.2, all RMI clients with keys APP_ODRMICLT, APP_ODRMISNMP, APP_ODAPITEST, and APP_ODEVENTREPORT are updated to work with a secure RMI-enabled OpenDeploy server.

Backward Compatibility

Any OOTB or custom clients that use the RMI client library from versions earlier than version 7.2 do not have support to pass the encrypted client password with the RMI calls.

If a OpenDeploy server runs in secure RMI-enabled mode, it will not serve any RMI requests from clients earlier than version 7.2

Any earlier OpenDeploy client than version 7.2 work seamlessly with a secure RMI-upgraded OpenDeploy server if the server runs in secure-RMI-disabled mode.


• • • •••

Chapter 8

Reports

Each OpenDeploy base server and receiver installation includes a reporting component used to publish events to a reporting server, which is installed as part of the administration package. Events sent by an OpenDeploy server to the reporting server are stored in a user-defined database. These events can subsequently be accessed by the administration server for viewing within the browser-based user interface.

Reports generated by an OpenDeploy server are durable. If the reporting server is temporarily unavailable, the OpenDeploy server retains the events until they can be successfully transferred after the reporting server goes back into service.

OpenDeploy provides the following reporting features available through the browser-based user interface:

Custom reports allow you to apply a search criteria based on deployment name, deployment owner, time frame, and other factors.

DAS custom reports are similar to custom reports, that give indications of database updates resulting from TeamSite event triggers.

ControlHub custom reports are similar to custom reports, that give indications of ControlHub activity. These reports are only available when using OpenDeploy with ControlHub.

SQL query reports. 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 are queries of either type that are saved and available for use at any time without having to perform additional configuration.


• • • •••

Chapter 8: Reports

28

Server ConfigurationEach OpenDeploy server participating in reporting must have:

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


See “Introduction to OpenDeploy” on page 25 for more information.

Enable Reports

You must enable the report 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 receive a prompt to decide whether to enable the reporting feature. 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 unavailable.


• • • •••

Server Configuration

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: od-home/(od-instance)/etc/eventReportingConfig.xml

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

Logs

The reporting feature generates it own log file. By default, this file resides in: od-home/(od-instance)/log/publisher.log

You can configure the log entries and file location in the reporting configuration file through the log element: <eventReportingConfiguration>

<log

name="reportingLog"

path="C:\Interwoven\OpenDeployNG\eventlog\publisher.log"

append="false"/>

...

</eventReportingConfiguration>

The log element contains the following associated attributes:

name denotes the unique name of the log element. For example: name="reportingLog"

path specifies the absolute path to the log file. For example:

path="od-home/eventlog/publisher.log"


• • • •••

Chapter 8: Reports

28

append specifies whether the file should be appended to (true) or truncated (false). If the value is true, new log entries append 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 are replaced by new entries. The default value is true.

Administration Server Configuration for Reports

This section describes the tasks required to configure the administration server for reporting. Configuration of the administration server for reporting is done in

Add Servers to the Report Environment

The odservers.cfg file is where you configure your administration server for reporting. This file resides in: admin-home/odadmin/config

The odservers.cfg file is an XML-based file you can edit with a text or XML editor. Here is an example of this file: <odConfiguration>

<reportingConfiguration hostName="mars"

restartInterval="120000">

<log name="openDeploySubscriberLog" path="C:/Interwoven/AdminServer/odadmin/log/

mars.log" append="true"/>

<log name="databaseLog" path="C:/Interwoven/AdminServer/odadmin/

log/HQPUBSJKM_database.log" append="true"/>

<odNode host="HQPUBSJKM" version="7.0.0" baseServer="true"

dasEnabled="false"/>

</reportingConfiguration>

<nodeSet>

<node name="localhost "host="127.0.0.1 "port="9173" />

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

</nodeSet>

</odConfiguration>

The odConfiguration element is the root element of the configuration. Within this element are elements and attributes for specifying the connection management, OpenDeploy server nodes included in the reporting, and logging. You can configure subprocess commands and environmental variables. The following sections describe each of these types of configurations.


• • • •••


Connection Management

The reportingConfiguration element is where you specify information related to the reporting server’s connection. <reportingConfiguration hostName="saturn" restartInterval="150000">

...


This element contains the following attributes:

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

restartInterval specifies the time interval (in milliseconds) between retries of failed connections. The default value is 300000 (300 seconds or 5 minutes).

Add OpenDeploy Servers to Reports

Each OpenDeploy server node you want to include in reporting must be specified by a separate odNode element in the odservers.cfg file: <reportingConfiguration ...>

...

<odNode host="mars" version="7.0.0" baseServer="true"

dasEnabled="false"/>

...


The odNode element contains the following attributes:

host specifies the logical name of the server (as it appears in the OpenDeploy user interface).

version specifies the release number of OpenDeploy. For example: version="7.0.0"

baseServer indicates whether (true or false) the server is a base server. If the server is a receiver, specify false.

dasEnabled indicates whether (true or false) DAS is enabled on the OpenDeploy server.

In addition to adding the odNode element, you must also add a corresponding node subelement within the nodeSet element: <nodeSet>

<node name="localhost host="127.0.0.1 "port="9173"/>

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


• • • •••

Chapter 8: Reports

28

...

</nodeSet>

The node entry contains the following attributes:

name specifies the logical name of the OpenDeploy server. The value must match what you specified of the odNode element’s host attribute value. For example: name="mars"

host specifies the resolvable name or the IP address of the host on which the OpenDeploy server resides. For example: host="mars.mycompany.com"

port specifies the RMI registry port of the OpenDeploy server.

By default, a node entry is included for the localhost. You must manually add any other servers to include in reporting.

Logs

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 resides in: admin-home/log

You can configure the database and subscriber log files using log elements: <reportingConfiguration ...>

<log

name="databaseLog"

path="admin-home/log/mars_database.log"

append="true"/>

<log

name="openDeploySubscriberLog"

path="admin-home/log/mars_subscriber.log"

append="true"/>

...



• • • •••


Subprocess Commands

You can specify subprocess commands in the reporting management configuration file with the process element: <odConfiguration>

...

<process ...>

...

</process

...

</odConfiguration>

The process element defines a series of subprocess command attributes associated with the reporting feature:

name denotes the unique name of the process element.

startCommand specifies the command-line tool used to start the subprocess. For example: startCommand="/usr/bin/cat"

See java.lang.Runtime.exec() in the Java API documentation for more information.

stopCommand specifies the command-line tool used to stop the subprocess. For example, if you have the following startCommand attribute value: startCommand="/etc/init.d/lpd start"

you may specify the corresponding stopCommand attribute value: stopCommand="/etc/init.d/lpd stop"

If a stopCommand value is not specified, the subprocess is destroyed.

startDir specifies the directory to change to before starting the subprocess. For example: startDir="/etc"

The default directory is the directory is the current one.

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 subprocess. For example: stderr="/export/home/jdoe/passwd.copy.err"


• • • •••

Chapter 8: Reports

28

Environmental Variables

You can specify environmental variables that pass to the subcommands using one or more environment elements within a process element. <process ...>

<environment .../>

</process

The environment element contains the following attributes:

name denotes the name of this environment variable. For example: name="POLICY_FILE"

This value does not need not be unique, as environment elements are processed in the order they appear in the XML. Each occurrence supersedes any previous occurrences with the same name.

value specifies the value to set the environment variable to. For example: value="od-home/openjms/src/etc/openjms.policy"

This value can contain references to Java system properties or to other environment elements that precede this one. For example: value="${OPENJMS_CP}${path.separator}${java.class.path}"

obscured indicates whether (true or false) the value attribute is encoded. Use the iwodpasscoder program to generate the encoded string. Refer to the iwodpasscoder section in the OpenDeploy Reference Guide for more information on this tool. The default value is false.

Report Server Database

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

Use 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 them are included with the OpenDeploy software. Refer to the OpenDeploy Release Notes for a list of 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: admin-home/odadmin/drivers. If the driver you need is not there, refer to the Web site for your database 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 basis for developing your own initialization script.

To configure your own reporting server database

1. Obtain the appropriate JDBC drivers. They are typically available from your database vendor’s Web site.

2. Stop the administration server service or daemon. See “Stop OpenDeploy” on page 49 for more information.

3. Open server.xml file using a text or XML editor. The file resides in: admin-home/servletd/conf.

4. Complete the ResourceParams element associated with the reporting database (name=jdbc/reportdb) and its various subelements and attributes.

Under the ResourceParams element are a series of name and value element pairs, for example: <ResourceParams name="jdbc/reportdb”>

<parameter>

<name>factory</name>

<value>org.apache.commons.dbcp.BasicDataSourceFactory</value>

</parameter>

<parameter>

<name>driverClassName</name>

<value>org.hsqldb.jdbcDriver</value>

</parameter>

<parameter>

<name>url</name>

<value>jdbc:hsqldb:C:\INTERW~1\ADMINS~1\odadmin\db\

eventReporting.db</value>

</parameter>

...

</ResourceParams>

Complete all the pair listed in the file, using the default values as a guide.


• • • •••

Chapter 8: Reports

29

NOTE

If you use SQL Server, you need to include the DatabaseName and SelectMethod attributes and their values in the URL string, for example: <value>jdbc:microsoft:sqlserver://myserver:1433; DatabaseName=mycompanydb_win;SelectMethod=Cursor;</value>

5. (For SQL Server only) Uncomment the following section: <!-- for mssqlserver only

<parameter>

<name>databaseName</name>

<value>REPORTDBNAME</value>

</parameter>

<parameter>

<name>selectMethod</name>

<value>cursor</value>

</parameter>

-- >

and substitute REPORTDBNAME with the correct value for the database.


7. Copy the JDBC driver .jar files associated with your database to the following locations:

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

admin-home/servletd/common/lib

8. Use the database tools to create and initialize the tables.

If you use 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 use a non-certified JDBC-compliant database, you must create your own initialization script. Refer to “Reporting Server Database Schema” in the OpenDeploy Reference for a list and description of the database schema to which the initialization script initializes. A file containing this schema 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 given 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 given database.

9. Navigate to: admin-home/odadmin/db

10. Open the iwoddbtool.bat file with a text editor and add each driver that you added in step 7 using the following syntax:


• • • •••


%ADMIN_HOME%/httpd/iwwebapps/openDeploy/lib/driver;

If you use a database driver that is an update of one already present in the iwoddbtool.bat file, such an Oracle 10 driver rather than an Oracle 9 one, you can replace the Oracle 9 driver (classes12.jar) with the Oracle 10 driver (ojdbc.jar). Autonomy Interwoven recommends you replace unused drivers with ones that are being used whenever possible, as the character limit of the iwoddbtool.bat file is 1024.

11. Save and close the iwoddbtool.bat file.

12. Type the following commands (in order) at the prompt:

Windows: iwoddbtool.bat -sql ODEvents_DBMS.sql

iwoddbtool.bat -sql quickreportslist_DBMS.sql

UNIX: ./iwoddbtool -sql ODEvents_DBMS.sql

./iwoddbtool -sql quickreportslist_DBMS.sql

where DBMS is the correct abbreviation for the database you use. Refer to “Database Abbreviations” in the OpenDeploy Release Notes for a list of these abbreviations.

13. Restart the administration server service or daemon. See “Starting OpenDeploy” for more information.

Reset the Database

Resetting the database clears it of existing reporting information and allows the reporting feature to have a fresh start. You can reset your reporting database, regardless of the type, through the OpenDeploy user interface by systematically deleting all event reporting data and saved report queries.

To reset the reporting database

1. Open the Report Maintenance window and delete the event reporting data. See “Manage Report Data” on page 312 for more information on this procedure.

2. Open the Edit Quick Report window and delete each saved quick report. See “Delete Quick Reports” on page 312 for more information on this procedure.

Reset the Hypersonic Database

In some cases, for example during demonstrations of the reporting feature, you may want to reset the default Hypersonic database. You can reset the Hypersonic database using the method described in “Reset the Database” on page 291, however, if the demonstration database is corrupt, you should perform the more comprehensive reset procedure described here.


• • • •••

Chapter 8: Reports

29

NOTE

If you use OpenDeploy with ControlHub, the process for resetting the Hypersonic database is different (see “Reset the Hypersonic Database When Using ControlHub” on page 292).

To reset the Hypersonic database

1. Stop the administration server service or daemon. See “Stop OpenDeploy” on page 49 for more information.


3. Delete the eventReporting.db.* files.

4. Type the following commands (in order) at the prompt:

Windows: iwoddbtool.bat -sql ODEvents_hSql.sql

iwoddbtool.bat -sql quickreportlist_hSql.sql

UNIX: ./iwoddbtool -sql ODEvents_hSql.sql

./iwoddbtool -sql quickreportlist_hSql.sql

5. Restart the administration server service or daemon. See “Start OpenDeploy” on page 45 for more information.

Reset 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

1. Stop the ControlHub reporting feature by typing 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 typing the following command at the prompt:

Windows: net stop iwservletd

UNIX: iw-home/private/bin/iwuiboot stop

where iw-home is the location where the ControlHub resides.


• • • •••


3. Stop the Hypersonic database by typing 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 typing 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: iw-home/tsreport/conf

7. Rename the tsreport.xml.example file, which resides in: iw-home/tsreport/conf to tsreport.xml.

8. Navigate to: iw-home/tsreport

9. Rename the following file to a name of your choice, keeping the .bat or .sh extension:

Windows: alldbschema.bat

UNIX: alldbschema.sh

10. Edit the renamed .bat or .sh file with a text editor, and replace the following tags with the specified value:


12. Type the renamed .bat or .sh file at the prompt and press Enter.


14. Type the following command at the prompt:

Windows: iwoddbtool.bat -sql ODEvents_hSql.sql

UNIX: ./iwoddbtool -sql ODEvents_hSql.sql

15. Type 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 typing the following command at the prompt:

[DBTYPE] hsqldb

[DBUSER] SA

[DBPASSWORD] (leave blank)

[DBSERVER] controlhub

[DBNAME] (leave blank)

[DBPORT] 9001


• • • •••

Chapter 8: Reports

29

Windows: net start iwservletd

UNIX: iwreset -ui

17. Restart the ControlHub reporting feature by typing the following command at the prompt:

Windows: net start iwtsreport

UNIX: iw-home/tsreport/bin/tsreport.sh start

Logs

The reporting server database maintains a log of activity. See “Logs” on page 283 for more information.

Upgrade Report Tables

If you upgrade 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”, 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 upgrade:

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” 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 fail. Reporting information and log errors are written to the following log file: admin-home/odadmin/log/server_subscriber.log, where server is the OpenDeploy server name.

Upgrade the Default Report Database

You can upgrade the default Hypersonic reporting database from OpenDeploy 5.6 to the current release with 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.

New Installation on Windows

To perform a new installation of the Hypersonic reporting database on Windows

1. Stop the administration server. See “Stop OpenDeploy” on page 49 for more information.

2. Open a command prompt window and navigate to: admin-home\odadmin\db

3. Type the following commands at the prompt: del eventReporting.db.*

iwoddbtool -sql ODEvents_hSql.sql

iwoddbtool -sql quickreportlist_hSql.sql

New Installation on UNIX

To perform a new installation of the Hypersonic reporting database on UNIX



3. Type the following commands at the prompt: rm eventReporting.db.*

./iwoddbtool -sql ODEvents_hSql.sql

./iwoddbtool -sql quickreportlist_hSql.sql

Upgrade on Windows

To upgrade a legacy Hypersonic reporting database on Windows


2. Open a command prompt window and navigate to: admin-home\odadmin\db

3. Type the following commands at the prompt: echo SHUTDOWN COMPACT; | iwoddbtool

4. Type the following command at the prompt, depending on the OpenDeploy release from which you upgrade:

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


• • • •••

Chapter 8: Reports

29

Upgrade on UNIX

To upgrade a legacy Hypersonic reporting database on UNIX



3. Type the following command at the prompt: echo "SHUTDOWN COMPACT;" | ./iwoddbtool

4. Type the following command at the prompt, depending on the OpenDeploy release from which you upgrade:

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

Use a Third-Party Database for a Store-and-Forward System

The internal OpenDeploy reporting message store-and-forward system can begin to use a large percentage of CPU time or fail under one or more of the following circumstances:

a very large number of files are deployed

deployments are scheduled often

the administration servers that subscribe to the reporting events are running and thus are unable to receive the events

If you experience performance problems related to event reporting, Autonomy Interwoven highly recommends 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

1. Stop the OpenDeploy server and the administration server (see “Stop OpenDeploy” on page 49).

2. Open the jmsConfig.xml file using a text or XML editor. This file resides in the following location: od-home/etc

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


5. Open the eventReportingConfig.xml file. This file resides in: od-home/etc


• • • •••

Custom Reports

6. Add the path to your JDBC drivers to the environment name="OPENJMS_CP" element.


8. Add the path to your JDBC drivers to your host’s CP environment variable.

9. Run the following command from the prompt to create the necessary tables in the database. od-home/lib/dbtool create config od-home/etc/jmsConfig

After running the command, the following message appears: Successfully created tables.

Otherwise, you may receive an error message from your JDBC driver or database about why it could not connect to the database. If this happens, you 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 may see “post-connection errors” about why it could not create certain tables. In 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 od-home/openjms/config/db and execute it with your database script execution tool.

You can verify 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 seem to have originated from OpenJMS. These messages indicate that the store-and-forward mechanism did not start properly. The error messages in the log help in determining the exact reason.

Custom ReportsCustom 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 programs.

Custom reports have a fixed structure that provides the basic information that typical OpenDeploy users want without having to build a complete report structure yourself, however, you can apply a variety of search criteria to this structure to refine the report to the deployment information and time frame you want.


• • • •••

Chapter 8: Reports

29

When generated, a custom report contains the following specific type of reports:

Deployment report displays information about the overall deployment.

Deployment leg report displays information about the deployment of files from a source to a specific target, either as a single target deployment, a fan-out deployment, or a multitiered deployment.

Manifest report displays information on the status of each item deployed in a specific leg of the deployment.

You can access a given deployment leg report from within the deployment report and a given manifest report from the deployment leg report.

Configure Custom Report Queries

Custom reports generate 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 (see Figure 55).

Figure 55 Custom Report window

The Custom Report window contains a variety of items that you can use to create a custom

report query, including the following search criteria:

deployment name

user name of the individual starting the deployment

whether to include all deployments or only deployments in the search that are complete, in-progress, or failed


• • • •••

Custom Reports

whether the report should cover OpenDeploy servers sending or receiving deployments

source and targets (if applicable) of the deployment

start and end time frame covered by the report

Create Custom Report Queries

To create a custom report query

1. Select Reports > Custom Report to display the Custom Report window (see “Custom Report window” on page 298).

2. Type 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. Type 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 (see Figure 56).

Figure 56 Target Host List when Receiving is selected

6. Select the button associated with the following time frame option you want to apply to the custom report and complete the information required for that option:

In the Last. Type a number and select the corresponding measure of time (hour, day, week, month) that the report covers.

From/To. Type the hours and minutes and select the dates from start to end that are covered by the report. You can select the Calendar buttons to display a calendar tool to select the days.


• • • •••

Chapter 8: Reports

30

You can click Reset at any time while creating a custom report to delete the values you typed and start again.

After you complete 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 “Generate Custom Reports” on page 300 and “Save Custom Reports as Quick Reports” on page 305 for more information.

Export Custom Report Queries

After you create your custom report query, you can export it to the SQL Query Report window, where you can further customize it. SQL query reports provide a greater level of flexibility to report 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 automatically imports into the SQL query displayed in the SQL Query Report window. See “SQL Query Reports” on page 307 for more information.

Generate Custom Reports

You can generate a custom report after you configure it by clicking Generate Report in the Custom Report window. The Deployment Report window opens (see Figure 57) containing the generated report.

Figure 57 Deployment Report window


• • • •••

Custom Reports

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 later. See “Save Custom Reports as Quick Reports” on page 305 for more information.

Deployment Report Structure

Deployment reports provide general information on the overall deployment. Deployment reports display in tabular format. Each column represents a category of information in the report:

Name column 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 given 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 completed, failed, or was 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.


• • • •••

Chapter 8: Reports

30

Deployment Leg Report

Deployment leg reports provide information on each leg of a specific deployment (see Figure 58).

Figure 58 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 multitier 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 displays.

Source column displays the source of the deployment leg. If a given instance of the OpenDeploy server is used, that instance name is also included.

Target column displays the target of the deployment leg.

Start column displays the start time of the deployment leg, using the following format: yyyy-mm-dd hh:mm:ss

End column displays the end time of the deployment leg, using the following format: yyyy-mm-dd hh:mm:ss

Encryption column displays the type of encryption used, if any.

Status column displays whether the deployment leg was completed or failed.

Detail column displays any other information about the deployment


• • • •••

Custom Reports

View Details button. Click to display the Leg Report Details window, which contains information on the deployment leg, including the leg name, source and target platforms, and source and target file locations (see Figure 59).

Figure 59 Leg Report Details window

Manifest Report

Deployment manifest reports provide information on the content associated with a specific deployment leg (see Figure 60).

Figure 60 Deployment Manifest Report

Click the link in the deployment’s Leg Label (Next Deployment) column entry to display the manifest report for that leg.

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: od-home/(od-instance)/tmp

Update Action column displays whether the deployed item was new, updated, or deleted.


• • • •••

Chapter 8: Reports

30

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.

Download 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 you can view and be used by another program, such as a database or a text editor. Figure 61 shows a custom report displayed in Microsoft Excel.

Figure 61 Generated Custom Report open in Microsoft Excel

Downloading a generated custom report allows you to modify the report, copy, and paste portions into other documents, or use the program to save it under a different format.

To download a generated custom

1. Click Download Report in the Deployment Report window. A message opens to prompt you 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 to save the file and type a file name.

4. Save the file.


• • • •••

DAS Custom Reports

Save Custom Reports as Quick Reports

You can save any custom report query as a quick report, where you can access and generate the report any time. Click Save Quick Report when you create your custom report query. You receive a prompt to name the report query. The named report is subsequently listed among the quick reports in the Deployment Reports window. See “Quick Reports” on page 310 for more information.

DAS Custom ReportsDatabase auto-synchronization (DAS) custom reports are similar to regular custom reports already described in this chapter in that you can type details and run or save a report query. DAS custom reports provide information about database updates resulting from TeamSite event triggers.

Refer to “Database Auto-Synchronization” 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 (see Figure 62).

Figure 62 DAS Custom Report window

You can save any unique DAS custom report configuration that you make in this window as a

quick report that you can generate later.


• • • •••

Chapter 8: Reports

30

To generate DAS custom reports

1. Select Reports > DAS Custom Reports to display the DAS Custom Report window.

2. Select a timestamp format from the Timestamp Format list.

The formats use the following syntax:

yy or yyyy indicates the two- or four-digit year (“2010” or “10”), respectively.

MM indicates the two-digit month (for example, January is “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. Type the period from which the report starts using the specified timestamp format in the From box.

4. Type 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 type 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 (path of workarea) list, and type 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 type 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 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.


• • • •••

SQL Query Reports

SQL Query ReportsSQL query reports allow you to design and compose your own report 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 custom report. You can save SQL query reports as quick reports for future use.

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.

You create SQL query reports in the SQL Query Report window (see Figure 63).

Figure 63 SQL Query Reports window

The SQL Query Report window opens when you select Reports > SQL Query Report in the

browser-based user interface. This window also opens when you click SQL Report in the Custom Report window, which allows 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.

The SQL Query Report window contains the information required for you to create your SQL report query.

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


• • • •••

Chapter 8: Reports

30

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

Access to Report 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 “Reset the Database” on page 291 for more information on configuring the user.

Refer to “Reporting Server Database Schema” 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 you write your own custom queries. Refer to the database documentation for more information.

Create SQL Queries

To create an SQL query

1. Select Reports > SQL Query Report to display the SQL Query Report window.

2. Review the available tables in the Valid Table Names list.

3. Review the available columns that correspond to a given 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 typing the valid tables, columns, and search conditions in the SELECT text box.

You can compose a query by copying and pasting a selected table or column name into the SELECT text box or by using drag-and-drop.


• • • •••

SQL Query Reports

You can click Reset at any time while creating an SQL query report to delete the values you typed and start again.

After you complete 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.

Generate SQL Query Reports

You can generate an SQL query report after you create the report query by clicking Generate Report in the SQL Query Report window. The Deployment Reports window opens containing the generated report (see Figure 64).

Figure 64 Generated SQL query report

Download 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 (CSV) file that you can view and use in another program, such as a database or a text editor. The procedure is the same as for custom reports. See “Download Custom Reports” on page 304 for more information.

Save 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 later. Click Save Quick Report when you create your SQL query report. You receive a prompt to name the report. That named report is subsequently listed among the quick reports in the Deployment Reports window.


• • • •••

Chapter 8: Reports

31

Quick ReportsYou 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 without additional report configuration. If you plan to run certain reports on a regular basis, consider saving them as quick reports.

Quick reports display in the Deployment Report window (see Figure 65).

Figure 65 Deployment Report window

The Quick Report list contains all quick reports that you can access and display. The following preconfigured quick reports are also included for use without additional configuration:

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.


• • • •••

Quick Reports

Add 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 Save Quick Report in the respective Custom Report, ControlHub Custom Report, or SQL Query Report window at the time of creation.

Edit Existing Entries

You can edit a custom, ControlHub, or SQL query listed in the Quick Report list through the Edit Quick Report window (see Figure 66).

Figure 66 Edit Quick Report window

To display the Edit Quick Report window

Select Reports > Edit Quick Report.

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 displays the associated Custom Report, ControlHub Custom Report, or SQL Query Report window, where you can modify the report. After you make changes, you can save the report under its existing name or save it with a new name. You can also generate the report.


• • • •••

Chapter 8: Reports

31

Delete Quick Reports

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.

Manage Report DataOpenDeploy includes a report maintenance feature to help administrators manage the amount of event report data that is maintained in the reporting database. The Report Maintenance window (see Figure 67) 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 you delete reporting data, you cannot recover it.

Figure 67 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

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 type the associated time and date information:


• • • •••

Report Database Size Guidelines

Older than the specified time period before the current date. Type the number and type of time measurement (hours, days, weeks, months). Report data older than the specified amount of time from now is deleted.

Older than the specified time period before a specified date. Type the time (hour and minute) and the date (day, month, year). Report data that is older than this specified time and date is deleted.

Click Reset if you want to clear your specified values and start again.

4. Click Remove Reports to remove the reporting data.

Report Database Size GuidelinesThis 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 the three databases.

Send 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, the average would be zero and you can use zero for that part of the formula.

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


• • • •••

Chapter 8: Reports

31

If you are not doing any database deployments, the average would be zero and you can use zero for that part of the formula.

Database AutoSynchronization (DAS)

(Number of DAS events) * 882

Capture Error Messages into an MIB FileYou can use a third-party error message trapping tool such as Trap Console to capture deployment error messages into the file iwopendeploy.mib. This file resides in: od-home/snmp

To capture error messages into the iwopendeploy.mib file

1. Upload the iwopendeploy.mib from its home directory (od-home/snmp) using your third-party trapping tool.

2. Compile the iwopendeploy.mib file.

3. Define the host for which you want to get the status (trap message).

4. Run the deployments that previously failed.

Now you can see the trap message for failed deployments. These messages appear in your third-party trapping tool with detailed information.


• • • •••

Chapter 9

Troubleshoot Administration Issues

This chapter describes how to troubleshoot OpenDeploy administration issues.

The RMI-based event report fails with OpenDeploy Admin 6.2.1 and OpenDeploy-Server 7.0

The RMI-based event reporting does not work if strictAuthentication is set to yes in <listenerProperties> of the target OpenDeploy 7.0 server for the following configurations:

OpenDeploy Base or Receiver 7.0 and OpenDeploy Admin 6.2.1 and earlier

OpenDeploy Base or Receiver 7.0 and Composite Application Provisioning Service version 3.0.1 and earlier

The RMI Based Event Reporting works only with OpenDeploy Admin 7.0 and greater.

Failure during database migration with the default Hypersonic reporting database

When upgrading to the current release and you are using the default Hypersonic reporting database, the migration of this database can fail.

If database migration failure occurs after the upgrade

1. Stop the administration server.


3. Delete all the eventReporting.db.* files.

4. Run the following command at the prompt:

Windows: echo SHUTDOWN COMPACT; | iwoddbtool


• • • •••

Chapter 9: Troubleshoot Administration Issues

31

NOTE

Note the lack of quotation marks on the Windows-based command.

UNIX: echo "SHUTDOWN COMPACT;" | iwoddbtool


Windows: copy hSqldb.oldver\hSqldb-bak.script eventReporting.db.script

UNIX: cp hSqldb.oldver/hSqldb-bak.script eventReporting.db.script

where ver is the OpenDeploy version from which you upgraded, for example 602.


Windows: echo SHUTDOWN COMPACT; | iwoddbtool.bat

UNIX: echo "SHUTDOWN COMPACT;" | iwoddbtool

7. Run one of the following commands depending on from which OpenDeploy version you are upgrading:

OpenDeploy 6.0 or 6.0.1: iwoddbtol -sql ODEvents-60-to-602_hSql.sql

OpenDeploy 5.6: iwoddbtol -sql ODEvents-56-to-602_hSql.sql

8. Restart the administration server.

In some cases, it may be necessary to reset the Hypersonic reporting database, either after an upgrade, or if the upgrade attempt fails. Refer to “Resetting the Hypersonic Database” in the OpenDeploy Administration Guide for more information.

Error 12505 occurs while deploying to the clustered database with DataDeploy

When performing a deployment to the clustered database (Oracle RAC) using DataDeploy, the database element’s db attribute’s value in the database.xml file must include the full path of the tns connection string, for example: <database name="oracle-rac-db"

db="(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=

TCP)(HOST = 10.120.3.39)(PORT = 1521)))(CONNECT_DATA

=(SERVICE_NAME=RAC.WORLD)))"

user="john_doe" password = "jdoe" vendor = "oracle"/>

If you assign the db attribute a value using the host:port:DB format, there is no connection to the RAC database and error “12505” occurs. For example: db="10.120.3.39:1521:RAC"


• • • •••

Synchronize user locales on Windows

In some cases, the OpenDeploy service does not read the system locale correctly on Windows. For example, if the system locale is set to Chinese, OpenDeploy may read the system locale as en_US rather than zh_TW. This is because the OpenDeploy service uses the locale of the default user profile and not of the current user profile. To avoid this problem, ensure that the default user locale is updated as well as the current user locale when changing the system locale settings.

1. Open the Control Panel and select the Regional and Language Options to display its window.

2. Select the Advanced tab.

3. Select Apply all settings to the current user account and to the default user profile under Default user account settings. This updates the registry key HKEY_USERS\.DEFAULT\Control Panel\International and thus the default user locale is updated.

Cannot share servletd with TeamSite HA

If you use TeamSite HA, your OpenDeploy administration server cannot share the servletd associated with TeamSite HA. OpenDeploy must use its own native servletd.

Non-root users cannot run the slibclean command on AIX

OpenDeploy does not automatically change the permission of slibclean so that non-root users can run it. Non-root AIX users must have the slibclean command permission changed manually prior to running it.

Error during schema creation on Scheduler DB with MySQL

You must create the schema according to the script file <od-home>/db/schedDB.script to avoid errors during schema creation on Scheduler DB with MySQL.


• • • •••

Chapter 9: Troubleshoot Administration Issues

31
• • • •••

IndexAadapter

logs 254

administration server 27

backups 164

CSF access service ports 140

HTTPS, configuring for CSF access service 140

HTTPS, configuring for OpenDeploy 141

keystore password, changing 142

logging 253

Microsoft Cluster 157

ports 139

reporting 284

RMI registry port 139

administration service configuration file 139

Administrator role 43, 117, 119

agentName attribute 168

agentProperties element 168

alert element 171

alert notifications 171

disabling 171

alertList element 171

allowDnrExecution attribute 185

allowed directories 192

reverse deployments 193

allowed hosts 190

checking 191

firewall deployments 161

IP addresses 191


allowedDirectories element 66, 192

allowedDnr element 201

allowedHosts element 66, 190, 191, 192

allowSet attribute 170

allowTargetFollowLinks attribute 181

append attribute 284

asynchronous deployments 116

attributes

agentName 168

allowDnrExecution 185

allowSet 170

allowTargetFollowLinks 181

append 284

baseServer 285

bindPort 177

blockCheckInterval 180

blockMaxWaitTime 180

bufferSize 168, 182

certPasswd 204

cfgPath 283

class 187

community 170

completedQueueCapacity (initiatorProperties) 198

completedQueueCapacity (listenerProperties) 198

connectRetries 185

daemon_port 210

dasEnabled 285

dbPassword 187, 189

dbUrl 187, 189

dbUser 187, 189

deploymentMaxWaitTime 201

directory 194, 233, 250

DOMAIN\\USER 55

enabled 282

enabled (das) 211

enabled (standalone) 210

enabled (webServices) 203

ENABLEINSTANCE 56

ENABLEREPORTING 56

ENABLESNMPINSTANCE 56

execProcess 210

host (httpsTransport) 204

host (httpTransport) 204

host (localNode) 176

host (node) 147, 170

host (odNode) 285

hostName 285

hsqlScriptSize 187, 190


• • • •••

32

isClearPassword 187, 189

jdbcDriverClass 189

keyFile 258, 259

level 194, 249

limit 212

logPath 169

max_threads 210

maxBackupIndex 194, 247, 249

maxBytes 194, 249, 251

maxDeploymentQueueLength 201

maxIdleTime 205

maxNumberOfDeploymentQueues 201

maxReadTime 205

maxThreads 205

minThreads 205

MYADMINRMIPORT 55

MYCLTPROXYPORT 55

MYDATABASEDEPLOYPORT 56

MYENCODING 56

MYJMSJNDIPORT 55

MYOPENJMSPORT 55

MYREPORTINGRMIPORT 55

MYRMIREGISTRYPORT 55

MYSNMPREQUESTPORT 55, 167

MYSNMPTRAPPORT 55

MYTARGETPORTNUMBER 55

MYWEBSVCHTTPPORT 56

MYWEBSVCODCERT 56

MYWEBSVCODCERTPD 56

name (alert) 171

name (environment) 288

name (log) 283

name (node) 147

name (path) 192, 212

name (process) 287

name (transportProperties) 182

nodes 190

obscured (environment) 288

odHostName 169

odInstanceName 169

odInterval 169

odRmiPort 169

path 283

pathRegistryChecking 179

pendSessions 197

percentDiskFull 212

port (httpsTransport) 204

port (httpTransport) 204

port (node) 147

previousArea 104

regex 201

requestPort 168

restartMarker (odReportingConfiguration) 285

runmode 210

sslCaCertificate 270

sslCertificate 269

sslCiphers 270

sslPrivateKey 270

sslVerifyPeer 270

startCommand 287

startDir 287

status 171

stderr 287

stdin 287

stopCommand 287

storePasswd 204

stout 287

strictAuthentication 182

strictPartnerChecking 177

transientDirectory 178

trapHost 168

trapPort 168

use_storename_prefix 210

value (environment) 288

version 285

authorization checking 134

Bbackups 162


base server 163

receiver 163

recovery procedures 165

reporting server 164

base server 26

backups 163

bootstrap administrator 138



• • • •••

•

logging 237, 252

modifying 131

reporting 195, 282

starting 48

base server configuration file 79

allowed Deploy and Run scripts 201


allowed hosts 190

bind port 177

buffer size 182

concurrency management 179

connection retries 185

database deployments 209

encoding 165, 176

encryption 196

host identification 176

logging 193

payload adapter-based 202

reporting 282

restricting access 182

scheduler database 186

specifying 132

temporary files, alternate location 178

transactional deployments, serialization 199

Web services 203

base server log file 78, 237

recovery 252

baseServer attribute 285

bind ports 177

bindPort attribute 177

blockCheckInterval attribute 180

blockMaxWaitTime attribute 180

bootstrap administrator 72

base server 138

configuring 136

disabling 133, 137

modifying 138

specifying 132

browsers, refresh 69

buffer size 182

bufferSize attribute 168, 182

Ccancellation, deployments 104

certificate authority

expiration 263

setup 261

third-party 265

certificates

expiration 265

generation 264

verification 267

certPasswd attribute 204

cfgPath attribute 283

ciphers 270

default 272

high-strength 271

low-strength 271

no-authentication 271

class attribute 187

command-line tools

iwodauthorize 123

iwodcmd 159

iwodcmd schedactivate 230

iwodcmd schedadd 224, 226

iwodcmd scheddelete 229

iwodcmd schedget 227

iwodcmd serverreset 66, 181

iwodcmd serverstatus 90

iwodcmd start 113, 114

iwodinsttool 56

iwodkeystoreaddcert 208

iwodkeystorecreatecert 207

iwodkeystoreexportcert 207

iwodkeystorelist 209

iwodnonroot 61

iwodservergetversion 90

community attribute 170

completed deployment list 197

received 198

sent 198

completedQueueCapacity

(initiatorProperties) attribute 198

(listenerProperties) attribute 198


registry target path entries 181

configuration files

administration service 139


32

base server 79

instance properties 54, 167

nodes 79, 145

receiver 79

reporting management 284

service 131

SNMP agent configuration 168

connectRetries attribute 185

ContentServices Foundation access service 27

key file 133

Microsoft Cluster 157, 158

cross-platform administration 145

custom reports 297

downloading 304

exporting to SQL 300

generating 300

queries 298, 299

saving as quick report 305

Ddaemon_port attribute 210

daemons 47

resetting 66

DAS 60

custom reports 305

das element 210

dasEnabled attribute 285

database deployments

base server configuration 209

runmode 211

databaseDeployment element 209

dbPassword attribute 187, 189

dbUrl attribute 187, 189

dbUser attribute 187, 189

definitions 31

delivery adapter log 254

Deploy and Run

allowed scripts 201

enabling 185

deployment

authorization checking 114

instances 115

reports 301

Deployment Configuration Composer 92

deployment configurations 30


allowed hosts 190

composing 91, 92

definitions 31

encoding 165

encryption 196

logging 113

syntax validation 199

uploading 94

XML code 92

deployment criteria

comparison-based 32

filelist-based 33

deployment groups 96

access controls 99

creating 96

directory permissions 98

viewing 97

deployment information stream format 185

deployment queuing 196

limitations 197

deploymentLegs element 212

deploymentMaxWaitTime attribute 201

deployments

asynchronous 116

authorization 120, 122, 123

cancelling 104, 116

compare phase 104

completed list 197

database 209

directory comparison 32, 35

fan-out 39

file list 33, 35

firewall 161

groups 96

host checking 177

information stream format 185

instance naming 101

monitoring 106

multi-tiered 40

organizing 96

parameter substitution 116

payload adapter-based 37, 202


• • • •••

•

performance throttling 211

pre-commit phase 104

queuing 196

reporting 281

reverse 42

routed 40

running 99, 113

scenarios 38

scheduled 215

scheduling 218

simulated 102, 115

single target 38

starting 99, 100, 114, 224

TeamSite comparison 32, 36

test 102

transactional 41

transfer phase 104

types 32

directory attribute 194, 233, 250

directory comparison 32, 35

disk element 212

dnrCmd element 201

dnrProperties element 185

DOMAIN\\USER attribute 55

Eelements

agentProperties 168

alert 171

alertList 171

allowedDirectories 66, 192

allowedDnr 201

allowedHosts 66, 190, 191, 192

das 210

databaseDeployment 209

deploymentLegs 212

disk 212

dnrCmd 201

dnrProperties 185

environment 288

eventReporting 195, 282

httpsTransport 204

httpTransport 203

initiatorProperties element 197

listenerProperties 177, 178, 179

localNode 176, 180, 190, 258, 259, 260, 270

log 283

logRules 66, 193, 251

name (localNode) 176

node 147, 170, 285

nodeSet 147, 285

odConfiguration 284

odNode 285

path 192

schedulerProperties 186

snmpAgentConfiguration 168

source 28

standalone 210

target 28

thresholdProperties 211

transportProperties 182, 185

webServices 203

enabled (das) attribute 211

enabled (standalone) attribute 210

enabled (webServices) attribute 203

enabled attribute 282

ENABLEINSTANCE attribute 56

ENABLEREPORTING attribute 56

ENABLESNMPINSTANCE attribute 56

encryption, types 196

environment element 288

error messages, trapping 314

event reporting for Microsoft Cluster 153

eventReporting element 195, 282

execProcess attribute 210

Ffan-out deployments 39

file deployment criteria

comparison-based 32

filelist-based 33

file descriptor limits, configuring 166

file integrity, checking 103

file list deployments 35

files

base server log 237, 252

log 78, 233, 250

macro deployment log 239


32

micro deployment log 242

receiver log 238

receiver macro deployment log 241

receiver micro deployment log 244

source macro deployment log 240

source micro deployment log 243

firewall authentication, ports 134


allowed hosts 161

configuration requirements 161

host matching 162

Hhost

(httpTransport) attribute 204

(localNode) attribute 176

(node) attribute 147, 170

(odNode) attribute 285

checking 177

names 146, 147, 149

reporting configuration file logging 283

host (httpsTransport) attribute 204

host (localNode) attribute 176

hostName attribute 285

hot folder feature 213

hsqlScriptSize attribute 187, 190

httpsTransport element 204

httpTransport element 203

IinitiatorProperties element 197

installation

instances 52


TeamSite 173

instance properties file 54, 167

attributes 55

instances 52

creating 58

daemons 53

DAS 60

directory structure 53

disabling 58

enabling 59

enabling SNMP 59

installation 52

iwodinsttool 56

naming 54, 101

properties files 54

removing 58

services 53

SNMP 59, 167

specifying 115

starting 60

stopping 60

target nodes 60

internationalization 165

base server configuration file 165

deployment configuration files 165

encoding 165

nodes configuration file 165

receiver configuration file 165

service configuration file 165

IP addresses

checking 191

multiple 149

isClearPassword attribute 187, 189

iwodauthorize 123

iwodcmd 159

configuration 159

hosts 160

migration 160

ports 160

schedactivate 230

schedadd 224, 226

scheddelete 229

schedget 227

serverreset 66, 181

serverstatus 90

start 113, 114

iwodinsttool 56

iwodkeystoreaddcert 208

iwodkeystorecreatecert 207

iwodkeystoreexportcert 207

iwodkeystorelist 209

iwodnonroot 61

restrictions 65

iwodservergetversion 90


• • • •••

•

JjdbcDriverClass attribute 189

KkeyFile attribute 258, 259

keystore file

adding certificates 208

creating certificates 207

displaying certificates 209

exporting certificates 207

managing 207

Llevel attribute 194, 249

limit attribute 212

listenerProperties element 177, 178, 179

localNode element 176, 180, 190, 258, 259, 260, 270

log element 283

log files

archived 251

base server 78

location 233

macro deployment 239

micro deployment 242

monitoring 76

permissions 233

receiver 78

receiver macro deployment 241

receiver micro deployment 244

recovery 252

size 250

source macro deployment 240

source micro deployment 243

viewing 234

logging 233

adapters 254


archive, maximum 247, 252

base server 237, 250

command line 246

default server-based 193

file location 233

file permissions 233

file size 250

hierarchy 250

host file recovery 252

levels 194, 245

macro deployment 113, 239, 250

micro deployment 242, 250

receiver 238, 250

receiver macro deployment 241

receiver micro deployment 244

recovery 253

reporting 283


rollover naming 251

rollover threshold 250

settings 195

SNMP 169

source macro deployment 240

source micro deployment 243

SSL encryption 273

user interface 246

logging levels

normal 100, 245, 249

verbose 100, 245, 249, 250

logical names 147

login 70

first time 72

logPath attribute 169

logRules element 66, 193, 251

Mmacro deployment logs 113, 239

recovery 253

max_threads attribute 210

maxBackupIndex attribute 194, 247, 249

maxBytes attribute 194, 249, 251

maxDeploymentQueueLength attribute 201

maxIdleTime attribute 205

maxNumberOfDeploymentQueues attribute 201

maxReadTime attribute 205

maxThreads attribute 205

memory management feature 212

micro deployment logs 242

recovery 253


administration package 157


32


ContentServices Foundation access service 157, 158

deploying from 156

deploying to 156

event reporting 153

installation 151

licensing 151

OpenDeploy server setup 152

prerequisites 151


setup 154

user interface 158

Web services 153

minThreads attribute 205

monitoring 106

completed deployments 110, 112

source deployments 110

target deployments 111

viewing options 108

monitoring deployments 197

multiple instances 60

target nodes 148

multi-tiered deployments 40

MYADMINRMIPORT attribute 55

MYCLTPROXYPORT attribute 55

MYDATABASEDEPLOYPORT attribute 56

MYENCODING attribute 56

MYJMSJNDIPORT attribute 55

MYOPENJMSPORT attribute 55

MYREPORTINGRMIPORT attribute 55

MYRMIREGISTRYPORT attribute 55

MYSNMPREQUESTPORT attribute 55, 167

MYSNMPTRAPPORT attribute 55

MYTARGETPORTNUMBER attribute 55

MYWEBSVCHTTPPORT attribute 56

MYWEBSVCODCERT attribute 56

MYWEBSVCODCERTPD attribute 56

Nname (alert) attribute 171

name (environment) attribute 288

name (localNode) element 176

name (log) attribute 283

name (node) attribute 147

name (path) attribute 192, 212

name (process) attribute 287

name (transportProperties) attribute 182

node element 147, 170, 285

nodes

attribute 190

configuration file 79, 145

encoding 146, 165

specifying 132

naming 146, 147

specifying target 147

target 145

nodeSet element 147, 285

non-Administrator, running OpenDeploy as 61

non-root

permissions, changing 62

running OpenDeploy as 61

start up script 63

normal logging level 100, 194, 245, 249

Oobject IDs (SNMP) 172

obscured (environment) attribute 288

odConfiguration element 284

odHostName attribute 169

odInstanceName attribute 169

odInterval attribute 169

odNode element 285

odRmiPort attribute 169

OpenDeploy

access, restricting 182


base server 26

configuration 129, 257

ContentServices Foundation access service 27

cross-platform administration 145

daemons 47

definitions 31

deployment configurations 30

encryption 196

file integrity 103

files, backing up 162

host names 146, 147


• • • •••

•

how works 28

installation 129, 257


logging 233

logical names 147

login 72

login options 70


monitoring 106


non-Administrator, running as 61

non-root, running as 61

physical host names 146

reconnecting to a restarted server 90

refreshing 66

reporting 281

reporting server 27

roles 43, 117

schedules 215

server names 147

servers 72

services 46, 47, 50, 51

SNMP 166

source server 26, 28

source/target relationship 28

starting 45, 47

status 90

stopping 49, 51

target servers 27, 28

user interface 49, 68, 69

version 90

Web services 203

Web site integrity 103

Pparameter substitution

deployments 116

scheduled deployments 226

path attribute 283

path element 192

pathRegistryChecking attribute 179

payload adapter-based deployments 37, 202

query-based 38

payload adapters

log 254

pendSessions attribute 197

percentDiskFull attribute 212

performance throttling 211

physical names 146

port (httpsTransport) attribute 204

port (httpTransport) attribute 204

port (node) attribute 147

ports 147


bind port 177

firewall 134

RMI registry 139

previousArea attribute 104

Qquick reports 310

list 310, 311, 312

SQL query reports 309

Rreceiver

backups 163


logging 238

modifying 131

reporting 195, 282

starting 48

receiver configuration file 79


encoding 165

reporting 282

restricting access 182

specifying 132

receiver log file 78, 238

recovery 252

receiver macro deployment log file 241

receiver micro deployment log file 244

regex attribute 201

reporting 195, 281


base server 282

custom reports 297

DAS custom reports 305


32

database sizing 313

deleting 312

enabling 282

host configuration 282

host reporting configuration file 283

logging 283

maintenance 312

quick reports 310

receiver 282

SQL reports 307

store-and-forward system 296

tables, upgrades 294

reporting management configuration file 284

reporting server 27

backups 164

connection management 285

environment variables 288

logging 286


servers, adding 285

sub-process commands 287

reporting server database 288

Hypersonic, resetting 291

resetting 291

upgrading 294

using own 288

reports

deployment 301

requestPort attribute 168

restartMarker (odReportingConfiguration) attribute 285



allowed hosts 192

host checking 178, 192

symmetric key encryption 259

RMI

binding IP address 136

firewall ports 134

server host name 136

roles 117

Administrator 43, 117, 119

server 119, 120

User 43, 118, 119, 120, 122

workflows 127

rollover threshold

archive, maximum 247, 252

logging 250

naming 251

size 251

routed deployments 40

runmode attribute 210

Sscenarios, deployment 38


activating 223, 230

command line 224

comments, use of 226

creating 218

database 186

deactivating 223, 230

deleting 222, 229

editing 222

end-date 226

one-time 225

parameter substitution 226

time zones 218

user interface 216

viewing 221, 227

scheduler database 186

In-Memory URL 188

JDBC drivers 189

script file size 190

Stand-Alone URL 188

URL options 187

schedulerProperties element 186

secure RMI feature 276

server configuration files

uploading 78

viewing 79

server groups 81

configuration files, editing for 86

creating 82

refreshing 89

updating files 87

viewing 83

server roles 120

access 119


• • • •••

•

servers

adding 73

changing 74

deleting 75

groups 81

log files 78

managing 72

monitoring 76

names 147

refreshing 80

service configuration file 131

firewall authentication 134


iwodcmd 159

services

resetting 66

starting 46, 47

stopping 50, 51

simulated deployments 102, 115

SNMP 166

agent configuration 168

agent configuration file 168

agent properties 168

alert notifications 171

community 170

disabling 167

enabling 167

instances 59

instances, configuring 167

logging 169

management information base 172

network manager host 170

object IDs 172

polling 169

set command 170

starting 167

stopping 167

snmpAgentConfiguration element 168

source element 28

source macro deployment log file 240

source micro deployment log file 243

source server 28

source servers

defined 26

SQL reports 307

downloading 309

generating 309

queries 307, 308

quick reports, saving as 309

SSL data transfer encryption

certificate authority 260, 261

certificate generation 264

certificate verification 267

ciphers 270

configuration 269

logging 273

OpenSSL defaults, changing 267

setting up 260

SSL errors 267

testing 272

sslCaCertificate attribute 270

sslCertificate attribute 269

sslCiphers attribute 270

sslPrivateKey attribute 270

sslVerifyPeer attribute 270

standalone element 210

startCommand attribute 287

startDir attribute 287

status attribute 171

stderr attribute 287

stdin attribute 287

stopCommand attribute 287

storePasswd attribute 204

stout attribute 287

strict authentication 182

ControlHub 184

external tasks 183

iwodcmd commands 183

strict partner checking 177

strictAuthentication attribute 182

strictPartnerChecking attribute 177

symbolic links, restricting 181

symmetric key encryption

configuration 258


syntax validation of deployment configurations 199


33

Ttarget element 28

target nodes 145

logical server names 147


physical host names 146

specifying 147

target replication farms

defining 149

target servers 28

defined 27

TeamSite

comparison 32

deployments 36

mount point 144

release 132

test deployments 102

thresholdProperties element 211

time zones, scheduled deployments 218

timeout, user interface 72

transactional deployments 41

serialization 199

transientDirectory attribute 178

transportProperties element 182, 185

trapHost attribute 168

trapPort attribute 168

Uuse_storename_prefix attribute 210

user interface 68

browser requirements 69

login 70


servers 72

starting 49, 69

timeout setting 72

User role 43, 118, 119, 122

access 120

Vvalue (environment) attribute 288

verbose logging level 100, 194, 245, 249, 250

version attribute 285

virtual memory limit 212

WWeb services 203

adding certificates 208

creating certificates 207

displaying certificates 209

exporting certificates 207

HTTP transport protocol 203

HTTPS configuration 206

HTTPS transport protocol 204

keystore file 207


multiple transport protocols 204

transport connection parameters 205

Web site integrity, checking 103

webServices element 203

XXML code 92


• • • •••

Documents

Open Deploy Admin Guide 7.2