7-1-1 Integration Server Administrators Guide

TitlePage
webMethods Integration Server

Administrators Guide
Version 7.1.1
July 2008
webMethods
Copyright & Docu mentID
ThisdocumentappliestowebMethodsIntegrationServerVersion 7.1.1andtoallsubsequentreleases. Specificationscontainedhereinaresubjecttochangeandthesechangeswillbereportedinsubsequentreleasenotesorneweditions. Copyright2008SoftwareAG,Darmstadt,Germanyand/orSoftwareAGUSA,Inc.,Reston,VA,UnitedStatesofAmerica,and/ortheir suppliers.Allrightsreserved. ThenameSoftwareAG,webMethods,andallSoftwareAGproductnamesareeithertrademarksorregisteredtrademarksofSoftwareAG and/orSoftwareAGUSA,Inc.Othercompanyandproductnamesmentionedhereinmaybetrademarksoftheirrespectiveowners.
Document ID: IS-AG-711-20080731
Table of Contents
About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1. The Role of the Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Does an Administrator Do? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Typical Administrative Responsibilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Integration Server Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Receiving Administrative Messages from the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Administrator User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Administrators Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding Backup Administrators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2. An Overview of the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Role of the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Retrieving Data for Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How the Server Executes Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Security Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3. Starting and Stopping the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Starting the webMethods Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Starting the Server from the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing Whether the Integration Server is a Windows Application or Windows Service . Switching the Server from a Windows Service to a Windows Application . . . . . . . . . . Switching the Server from a Windows Application to a Windows Service . . . . . . . . . . What Happens When You Start the Server? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to Tell if the Server Is Running Correctly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Shutting Down the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Active Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Restarting the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Server Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Integration Server Data Integrity and Recoverability Considerations . . . . . . . . . . . . . . Critical Integration Server Data Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4. Using the Integration Server Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is the Integration Server Administrator? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Starting the Integration Server Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 15 16 17 18 18 19 19 19 19 20 21 22 22 24 25 26 27 28 28 29 30 31 33 34 34 36 36 37 37 38 38 39 40 41 42 42
webMethods Integration Server Administrators Guide Version 7.1.1
Table of Contents
Basic Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Getting Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 The Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 5. Managing Users and Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Users and Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Purpose of Users and Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining a User Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Predefined User Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding User Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Removing User Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing Passwords and Password Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . Password Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disabling and Enabling Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disabling a User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling a User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Predefined Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding Users to a Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Removing Users from a Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Group Membership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Removing Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6. Configuring the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing and Changing Licensing Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The License Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing or Changing the License Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Renewal Reminders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Renewing a Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Licensed Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing the Server Thread Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting the Session Timeout Limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Outbound HTTP Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Outbound HTTP Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up Aliases for Remote Integration Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding an Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing the Connection to a Remote Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing an Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting an Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up Aliases for Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding an Endpoint Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Associate an Endpoint Alias with a Binder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing an Endpoint Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting an Endpoint Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 46 46 47 48 48 49 50 50 52 53 53 54 55 56 57 58 59 60 61 62 62 62 63 63 63 64 65 66 67 68 69 71 71 71 72 72 74 74 75
Table of Contents
Specifying a Third-Party Proxy Server for Outbound Requests . . . . . . . . . . . . . . . . . . . . . Bypassing a Proxy Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Where the Integration Server Writes Logging, Status, and Other Information . Switching from the Embedded Database to an External RDBMS . . . . . . . . . . . . . . . . . . . . Working with Extended Configuration Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Integration Server to Work with Servers Running HTTP 1.0 and Above . . Specifying Character Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using a 64-bit JVM on Solaris and HP-UX Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Publishing Information about Integration Server Assets . . . . . . . . . . . . . . . . . . . . . . . . . . . 7. Configuring Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Considerations for Adding Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding an HTTP Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Advanced Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding an HTTPS Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding a File Polling Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding an FTPS Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding an FTP Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding an Email Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding an HTTP Diagnostic Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding an HTTPS Diagnostic Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Suspending an HTTP/HTTPS Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Resuming an HTTP/HTTPS Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying an FTP/FTPS Port Range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing the Primary Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting a Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing a Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling/Disabling a Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding a Security Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8. Configuring Document Stores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring the Default Document Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring the Trigger Document Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Maintaining Inbound Document History for Received Documents . . . . . . . . . . . . . . . . . . . Enabling Inbound Client-Side Queuing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring the Outbound Document Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting the Capacity of the Outbound Document Store . . . . . . . . . . . . . . . . . . . . . . . . Selecting a User Account for Invoking Services Specified in Broker/Local Triggers . . . . . . Managing the Document History Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9. Connecting Integration Server to Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Establishing the Primary Port for Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring an Integration Server-to-Broker Server Connection . . . . . . . . . . . . . . . . . . . . .
75 77 78 79 79 80 81 81 82 83 84 85 85 87 88 93 98 101 103 107 109 114 115 115 117 117 118 118 119 121 122 123 124 126 127 127 128 128 129 131 132 132 132
Table of Contents
Specifying the Keep-Alive Mode for the Broker Connection . . . . . . . . . . . . . . . . . . . . . . . . Setting Server Configuration Parameters for Keep-Alive Mode . . . . . . . . . . . . . . . . . . Normal Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Listen Only Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10. Managing Server Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up Administrators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up Developers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling and Disabling Well-Known User Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FIPS 140-2 Compliance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11. Securing Communications with the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Background About SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SSL and the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . When the Integration Server Is an SSL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . When the Integration Server Is an SSL Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . Presenting Multiple Client Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Checklist for Using SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Items You Need Before Configuring SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Obtaining the Certificate of the CA that Signed an Internet Resources Certificate . . . . . . . Configuring the Server to Use SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring the Server to Present Multiple Client Certificates . . . . . . . . . . . . . . . . . . . . . . . Checklist for Presenting Multiple Client Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . Obtaining Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up a Remote Server Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Coding Your Flow Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling Server SSL Security Level by Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12. Controlling Access to Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling Access to Resources by Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Restricting IP Addresses that Can Connect to a Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling IP Access to All Ports (Globally) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Allow Inbound Connections from Specified Hosts (Deny all Others) . . . . . . . . . . . Deny Inbound Connections from Specified Hosts (Allow All Others) . . . . . . . . . . Controlling IP Access to Individual Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Allow Inbound Requests from Specified Hosts (Deny All Others) . . . . . . . . . . . . . Deny Inbound Requests from Specified Hosts (Allow All Others) . . . . . . . . . . . . . Restricting the Services Available from a Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Allow Access to Specified Services (Deny All Others) . . . . . . . . . . . . . . . . . . . . . . . . . Deny Access to Specified Services (Allow All Others) . . . . . . . . . . . . . . . . . . . . . . . . . Controlling the Use of Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
134 136 136 136 137 139 140 141 142 143 143 145 146 146 146 146 147 148 148 149 151 151 153 154 155 155 155 156 157 158 158 159 159 160 161 162 162 163 164 165 166 167
Table of Contents
Controlling Access to Resources with ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Package Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Implicit and Explicit Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Users that Belong to More than One Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Predefined ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . When Does the Server Perform ACL Checking? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Allowing or Denying Group Access to ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Default Settings and Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Happens When You Change Existing ACL Assignments . . . . . . . . . . . . . . Assigning ACLs to Folders, Services, and Other Elements . . . . . . . . . . . . . . . . . . . . . Assigning ACLs to Files the Server Can Serve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Rules for Using .access Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Removing ACL Protection from a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13. Authenticating Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Client Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . HTTPS Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTPS Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Checklist for Using Client Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Items You Need Before Configuring Ports to Request Client Certificates . . . . . . . . . . Importing a Client Certificate and Mapping It to a User . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing a Certificate Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring How Ports Handle Client Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Basic Authentication (User Names and Passwords) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Responding to Integrated Windows Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User Name, Password, and Domain Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Activating Integrated Windows Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14. Securing Your Server with PKI Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About PKI Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PKI Profile Checking Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Supported Hardware and Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring PKI System Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a PKI Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating the PKI Profile Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Connecting to and Disconnecting from the PKI System . . . . . . . . . . . . . . . . . . . . . . . . . . . Logging in a PKI Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
168 168 170 171 171 172 173 173 174 174 175 176 176 177 178 179 181 182 182 183 184 185 186 186 187 188 188 189 191 195 196 196 199 200 200 201 201 201 202 204 207 208 208
Table of Contents
Deleting a PKI Profile Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing and Updating Information for a PKI Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing or Updating PKI Profile Alias Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Determining Whether a PKI Profile Is Logged In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Recovering a PKI Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing the Password for a PKI Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Updating Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Exporting a PKI Profile from the File System to an HSM Device . . . . . . . . . . . . . . . . . . . . . Installing an Entrust PKI Proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Password Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About CRL Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How Often Is the CRL Downloaded? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15. Setting Up a Reverse HTTP Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How Reverse HTTP Gateway Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Advantages to Reverse HTTP Gateway vs. Traditional Third-Party Proxy Servers . . . . . . Clustering in the Reverse HTTP Gateway Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up the Reverse HTTP Gateway Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up the Gateway External Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up the Gateway Registration Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Connecting Your Internal Server to a Reverse HTTP Gateway Server . . . . . . . . . . . . . . . . Setting Up the Internal Registration Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performing Client Authentication on the Reverse HTTP Gateway Server . . . . . . . . . . . . . . Frequently Asked Questions About Reverse HTTP Gateway . . . . . . . . . . . . . . . . . . . . . . . 16. Outbound Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing Outbound Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing the Master Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing the Expiration Interval for the Master Password . . . . . . . . . . . . . . . . . . . . . . . . . About the configPassman.cnf File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Outbound Password Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling Name and Location of Outbound Password File . . . . . . . . . . . . . . . . . . . . Controlling Encryption of Outbound Password File . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Master Password Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Storing the Master Password in a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Prompting for the Master Password at Server Initialization . . . . . . . . . . . . . . . . . . . . . What To Do if You Lose or Forget Your Master Password . . . . . . . . . . . . . . . . . . . . . . . . . When There Are Problems with the Master Password or Outbound Passwords at Startup Determining Whether You Can Restore the Passwords . . . . . . . . . . . . . . . . . . . . . . . . Restoring the Master Password and Outbound Password Files . . . . . . . . . . . . . . . . . . Resetting the Master Password and Outbound Passwords . . . . . . . . . . . . . . . . . . . . . Email Listeners and Package Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
209 209 210 211 211 213 214 215 216 217 217 218 219 220 221 222 222 223 224 230 233 233 237 238 241 242 242 244 244 245 246 246 246 246 247 247 248 248 249 250 250 251
Table of Contents
17. Configuring a Central User Directory or LDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of How Integration Server Works with Externally Defined Users and Groups . . . How the Server Uses Externally Defined Users and Groups . . . . . . . . . . . . . . . . . . . . When the Server Accesses Externally Defined Information . . . . . . . . . . . . . . . . . . . . . How Integration Server Authenticates Externally Defined Clients . . . . . . . . . . . . . . . . Configuring Central User Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Stopping Use of Central User Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of Using LDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About LDAP and Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring the Server to Use LDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mapping an LDAP Users Access to ACL(s) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Stopping Use of an LDAP as an External Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . Considerations for User Accounts and Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Granting Administrator Privileges to External Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Granting Developer Privileges to External Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Granting Access to Services and Files to External Users . . . . . . . . . . . . . . . . . . . . . . . . . . 18. Managing Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Predefined Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How the Server Stores Package Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Manifest File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Finding Information about Your Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing the Packages that Reside on Your Server . . . . . . . . . . . . . . . . . . . . . . . . . . . Filtering the List of Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Determining Whether the Server Successfully Loaded the Package . . . . . . . . . . Determining Whether the Package Is Enabled or Disabled . . . . . . . . . . . . . . . . . Displaying Information about a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Displaying Information about Services and Folders in a Package . . . . . . . . . . . . . . . . Displaying Documentation for a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Activating a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reloading a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disabling a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Recovering a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Archiving a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Copying Packages from One Server to Another . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of Package Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Version Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Who Can Subscribe? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
253 254 255 255 255 256 256 259 260 260 261 267 267 267 269 270 271 273 274 275 277 277 279 280 281 281 283 283 284 287 287 288 288 289 289 290 290 291 291 292 292 293 297 298
Table of Contents
Guidelines for Using Package Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Publishing Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Displaying Subscribers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding Subscribers from a Publishing Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . Updating Subscriber Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Removing Subscribers for a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Publishing a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying File and Version Information for a Release or Archive . . . . . . . . . . . . . . . . The Subscribing Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Displaying Packages That Your Server Subscribes To . . . . . . . . . . . . . . . . . . . . . Manually Pulling a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Subscribing to a Package from a Subscribing Server . . . . . . . . . . . . . . . . . . . . . . Updating Your Subscription Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Canceling a Subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing a Package Published by Another Server . . . . . . . . . . . . . . . . . . . . . . . . 19. Caching Service Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is Caching? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . When Are Cached Results Returned? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Resetting the Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Service Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20. Configuring Guaranteed Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About Guaranteed Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring the Server for Guaranteed Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Settings Shared by Both Inbound and Outbound Transactions . . . . . . . . . . . . . . . . . . Settings for Inbound Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Settings for Outbound Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Administering Guaranteed Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Shutting Down Guaranteed Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reinitializing Guaranteed Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Inbound Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Outbound Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying an E-Mail Address and SMTP Server for Error Messages . . . . . . . . . . . . . . . . . 21. Managing Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Fully-Qualified Service Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Package Names and Service Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Finding Information about Services and Folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Listing Folders and Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Displaying Information about a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Manually Adding a Service to the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running Services When Packages Are Loaded, Unloaded, or Replicated . . . . . . . . . . . . .
298 299 299 300 301 303 303 305 308 309 309 310 313 315 316 319 320 320 322 322 323 324 325 325 325 327 328 328 329 329 330 330 331 332 332 333 334 334 334 336 336 336 337
10
Table of Contents
What Is a Startup Service? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is a Shutdown Service? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is a Replication Service? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Guidelines for Using Startup, Shutdown, and Replication Services . . . . . . . . . . . . . . . Running Services in Response to Specific Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Scheduling Services to Execute at Specified Times . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Scheduling a User Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Once Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Simple Repeating Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Complex Repeating Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Clustering Target Node Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Scheduled User Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Updating Scheduled User Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Suspending Scheduled User Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Resuming Suspended Scheduled User Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Canceling Scheduled User Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing the Scheduled System Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22. Locking Administration and Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Choosing Local Server Locking or VCS Integration Locking . . . . . . . . . . . . . . . . . . . . . . . . Disabling and Re-enabling Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Remote Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Server User Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Package Replication and Publishing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Package and Folder Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Upgrading webMethods Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23. Managing Broker/Local Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing Document Retrieval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Increasing or Decreasing Threads for Document Retrieval . . . . . . . . . . . . . . . . . . . . . When to Increase or Decrease Threads for Document Retrieval . . . . . . . . . . . . . Decreasing the Capacity of Trigger Document Stores . . . . . . . . . . . . . . . . . . . . . . . . . Suspending and Resuming Document Retrieval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Suspending and Resuming Document Retrieval for all Triggers . . . . . . . . . . . . . . Suspending and Resuming Document Retrieval for a Specific Trigger . . . . . . . . . Managing Document Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Increasing or Decreasing Threads for Document Processing . . . . . . . . . . . . . . . . . . . When to Increase or Decrease Threads for Processing Documents . . . . . . . . . . Decreasing Document Processing for Concurrent Triggers . . . . . . . . . . . . . . . . . . . . .
337 337 338 338 338 339 339 340 340 341 344 350 350 351 352 352 353 355 356 356 356 356 357 359 359 359 359 359 360 360 361 362 363 363 364 365 366 367 369 371 371 372 373
11
Table of Contents
Suspending and Resuming Document Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . Suspending and Resuming Document Processing for all Triggers . . . . . . . . . . . . Suspending and Resuming Document Processing for Specific Triggers . . . . . . . Limiting Server Threads for Broker/Local Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Cluster Synchronization for Trigger Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Cluster Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Cluster Synchronization at Run Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Monitoring Cluster Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modifying Broker/Local Trigger Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24. Using Integration Server to Manage XA Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of XA Transaction Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How the Integration Server Persists the State of a Transaction . . . . . . . . . . . . . . . . . . How the Integration Server Resolves Uncompleted Transactions . . . . . . . . . . . . . . . . About Unresolved XA Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Details for an Unresolved XA Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring XA Options in Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling or Disabling XA Transaction Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring the XA Recovery Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring XA Server Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Manually Resolving a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A. Integration Server Deployment Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Stage 1: Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Stage 2: Basic Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Stage 3: Setting Up Users, Groups, and ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Stage 4: Publishing Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Stage 5: Installing Run-Time Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Stage 6: Preparing Clients for Communication with the Server . . . . . . . . . . . . . . . . . . . . . . Stage 7: Setting Up Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Stage 8: Startup and Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Stage 9: Archive Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B. Server Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . watt.config. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . watt.core. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . watt.debug. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . watt.debug2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . watt.net. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . watt.security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . watt.server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . watt.tx. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . watt.xslt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
375 375 377 379 380 381 381 383 384 387 388 388 389 390 391 392 393 394 394 395 397 398 398 399 400 401 402 402 403 404 405 407 408 408 408 409 410 411 416 418 444 445
12
Table of Contents
C. Diagnosing the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring the Diagnostic Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Diagnostic Thread Pool Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Diagnostic Port Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Diagnostic Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Starting the Integration Server in Safe Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . When the Server Automatically Places You in Safe Mode . . . . . . . . . . . . . . . . . . . . . . . . . Generating a Thread Dump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D. Wireless Communication with the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . How Does the Integration Server Communicate with Wireless Devices? . . . . . . . . . . . . . . Using URLs for Wireless Access to the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . Invoking a Service with a URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Requesting a WML or HDML Page with a URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . WML and HDML Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
447 448 448 448 449 449 450 451 452 453 454 456 456 457 459
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
13
Table of Contents
14
About This Guide

ThisguideisfortheadministratorofawebMethodsIntegrationServer.Itprovidesan overviewofhowtheserveroperatesandexplainscommonadministrativetaskssuchas startingandstoppingtheserver,configuringtheserver,settingupuseraccountsand security,andmanagingpackagesandservices.
Document Conventions
Convention Bold Italic Description Identifieselementsonascreen. Identifiesvariableinformationthatyoumustsupplyorchangebased onyourspecificsituationorenvironment.Identifiestermsthefirst timetheyaredefinedintext.Alsoidentifiesserviceinputandoutput variables. IdentifiesstoragelocationsforservicesonthewebMethods IntegrationServerusingtheconventionfolder.subfolder:service. Identifiescharactersandvaluesthatyoumusttypeexactlyor messagesthatthesystemdisplaysontheconsole. Identifieskeyboardkeys.Keysthatyoumustpresssimultaneously arejoinedwiththe+symbol. Directorypathsusethe\directorydelimiterunlessthesubjectis UNIXspecific. Optionalkeywordsorvaluesareenclosedin[].Donottypethe[] symbolsinyourowncode.
Narrow font
Typewriter font
UPPERCASE \ []
15
About This Guide
Additional Information
ThewebMethodsAdvantageWebsiteathttp://advantage.webmethods.comprovides youwithimportantsourcesofinformationaboutwebMethodsproducts: Troubleshooting Information.ThewebMethodsKnowledgeBaseprovides troubleshootinginformationformanywebMethodsproducts. Documentation Feedback.ToprovidefeedbackonwebMethodsdocumentation,goto theDocumentationFeedbackFormonthewebMethodsBookshelf. Additional Documentation.Startingwith7.0,youhavetheoptionofdownloadingthe documentationduringproductinstallationtoasingledirectorycalled _documentation,locatedbydefaultunderthewebMethodsinstallationdirectory. Inaddition,youcanfinddocumentationforallwebMethodsproductsonthe webMethodsBookshelf.
16
The Role of the Administrator

What Does an Administrator Do? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Typical Administrative Responsibilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Integration Server Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Receiving Administrative Messages from the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Administrator User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding Backup Administrators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 18 19 19 19 20
17
1 The Role of the Administrator
What Does an Administrator Do?

InanISenvironment,theadministratorisresponsibleforinstalling,configuring,and maintainingthewebMethodsIntegrationServer.Heorsheisalsoresponsiblefor ensuringtheserverissecure,availabletoclients,andrunningatpeakperformance. Usually,onepersonisappointedastheadministrator,althoughmostsitesidentifyat leastoneotherpersontoactasabackup.
Typical Administrative Responsibilities

IfyouarethewebMethodsIntegrationServerAdministratorforyoursite,youmightbe involvedinsomeorallofthefollowingactivities. Installing and upgrading the Integration Server,whichincludestaskssuchasequippingthe servercomputerwithappropriatehardwareandsoftware,downloadingand installingtheserverprogram,andimplementingupgradesasneeded. Starting and stopping the server,whichincludesshuttingdowntheserverwhen necessary(e.g.,forroutinemaintenanceorreconfiguration)andrestartingit afterwards.Italsoincludesperformingyoursitesstandardrecoveryprocedures followingahardwareorsoftwarefailureoftheservercomputer.Forinformation abouttheseactivities,seeChapter 3,StartingandStoppingtheServer. Configuring server settings,whichincludessettingbasicoperatingparameterssuchas themaximumsessionlimits,logfileoptions,andportassignments.Forinformation abouttheseactivities,seeChapter 6,ConfiguringtheServer. Administering users and groups,whichincludesdefiningusernamesandpasswordsfor authorizedusersandassigningthemtogroups.Forinformationaboutthistask,see Chapter 5,ManagingUsersandGroups.Alternatively,youcanconfigurethe servertoacquireuserandgroupinformationfromanexternalsystem(e.g.,LDAP). Formoreinformation,seeChapter 17,ConfiguringaCentralUserDirectoryor LDAP. Administering server security,whichincludesidentifyingotheradministrators,assigning accesscontrolstoindividualservices,andconfiguringtheserversuseofdigital certificates.Formoreinformationaboutthistask,seeChapter 10,ManagingServer Security. Managing packages and services,whichincludestaskssuchasactivating/deactivating services,copyingpackages,andupdatingservicesand/orpackagesasnecessary.For moreinformationaboutthistask,seeChapter 18,ManagingPackagesand Chapter 21,ManagingServices.
18
The Integration Server Administrator

TheIntegrationServerAdministratoristheutilityyouusetoaccomplish administrativetasks.Youuseittomonitorserveractivity,examineloginformation,add users,enable/disableservices,andadjusttheserversperformancefeatures.For informationabouttheIntegrationServerAdministrator,seeChapter 4,Usingthe IntegrationServerAdministrator.
Receiving Administrative Messages from the Server

TheIntegrationServerissuesemailmessagesforavarietyoffailureconditions(for example,internalerrors,bindingerrors,andtransactionmanagererrors).Asan administrator,youaretheonewhoshouldreceivethesemessagesandtakeappropriate actionwhenerrorsoccur. Toensurethatyou(oranappropriatealternate)receivemessagesfromtheserver,you mustsettheEmail NotificationparametersusingtheIntegrationServerAdministratoras describedinSpecifyinganEMailAddressandSMTPServerforErrorMessageson page 330.
The Administrator User

EveryIntegrationServerisinstalledwithapredefineduseraccountcalled Administrator.Bydefault,thisuseristheonlyonewhocanperformadministrative taskswiththeIntegrationServerAdministrator.
The Administrators Password

ThepredefinedpasswordassignedtotheAdministratoruseraccountismanage. Important! ThepredefinedpasswordfortheAdministratoraccountismanage.The predefinedpasswordfortheDeveloperaccountisisdev.Thepredefinedpassword fortheReplicatoraccountisiscopy. ChangeallofthesepasswordsimmediatelyafterinstallingthewebMethods IntegrationServer.Otherwise,yourserverwillbevulnerabletoanyonewhoknows thedefaultpasswordsthatwebMethodsinstallsonitsservers.Whenassigninga password,makeitsomethingthatisdifficulttoguess.Forexample,makeitamixture ofupperandlowercaseletters,numbers,andspecialcharacters.Donotuseaname,a phonenumber,yourlicenseplate,yoursocialsecuritynumber,orothergenerally availableinformation.Donotwritepasswordsdown.Donottellanyonethe passwordunlessyouaresureofthatpersonsidentity. Tolearnhowtochangepasswords,seeChangingPasswordsandPassword Requirementsonpage 50.
19
Adding Backup Administrators

Itisagoodideatodesignateatleastoneindividualasabackupadministrator,whocan administertheIntegrationServerwhenyouarenotavailable. Toaddabackupadministratortoyourserver,createaregularuseraccountfortheuser (ifheorshedoesnotalreadyhaveone);thenaddthatuseraccounttothe Administratorsgroup. OnlymembersoftheAdministratorsgroupcanusetheIntegrationServer Administrator.Forinformationaboutcreatinguseraccountsandaddingthemtogroups, seeChapter 5,ManagingUsersandGroups. Note: Ifyouuseanexternaldirectoryforuserandgroupinformation,seeGranting AdministratorPrivilegestoExternalUsersonpage 269forinformationabout addingadministrators.
20
An Overview of the Server

22 22 26 27 28 28
The Role of the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How the Server Executes Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Security Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
21
2 An Overview of the Server
The Role of the Server

ThewebMethodsIntegrationServerhostspackagesthatcontainservicesandrelated files.TheIntegrationServercomeswithseveralpackages.Forexample,itincludes packagesthatcontainbuiltinservicesthatyourdevelopersmightwanttoinvokefrom theirservicesorclientapplicationsandservicesthatdemonstratesomeofthefeaturesof theIntegrationServer.Youcancreateadditionalpackagestoholdtheservicesthatyour developerscreate.Yourdeveloperscancreateservicesthatperformfunctions,suchas, integratingyourbusinesssystemswiththoseofyourpartners,retrievingdatafrom legacysystems,andaccessingandupdatingdatabases. TheIntegrationServerprovidesanenvironmentfortheorderly,efficient,andsecure, executionofservices.Itdecodesclientrequests,identifiestherequestedservices,invokes theservices,passesdatatothemintheexpectedformat,encodestheoutputproducedby theservices,andreturnsoutputtotheclients. Additionally,theserverauthenticatesclients,verifiesthattheyareauthorizedtoexecute therequestedservice,maintainsaudittraillogs,andpromotesthroughputusing facilitiessuchasserviceresultcaching.
Architecture
TheIntegrationServerlistensforclientrequestsononeormoreports.Youcanassociate thetypeofprotocolthattheserverusesforeachport.TheserversupportsHTTP,HTTPS, FTP,FTPS,andemailports. Whenapplicationsarebuiltaroundthethinclient,theapplicationusesanHTTPor HTTPSportforcommunicationwiththeserver.WhenusingHTTPorHTTPSports,the clientscommunicateusingthewebMethodsRemoteProcedureCall(RPC).Becausethe serversupportsbothHTTPandHTTPS,itcanlistenonanHTTPportfornonsecure clientrequestsandanHTTPSportforsecurerequests. Note: UnlikeHTTP,FTP,andemail,HTTPSandFTPSprovideforsecuredata transmission.Theydothisthroughencryptionandcertificates.WithoutHTTPSor FTPS,unauthorizedusersmightbeabletocaptureormodifydata,useIPspoofingto attackservers,accessunauthorizedservices,orcapturepasswords.Ifyoumustpass passwords,makesurethebackendapplicationhasminimalprivileges. TointeractwiththeserverwithoutusingthewebMethodsRPC,useanFTPorFTPSport. AtypicaluseforanFTPorFTPSportistogetadirectorylisting,changetothedirectory thatcontainstheserviceyouwanttoinvoke,putafilethatcontainsinputtotheservice, andruntheservice.Theserverreturnstheoutputfromtheservicetothedirectoryin whichtheserviceresides.Useanemailporttoreceiverequeststhroughanemailserver, suchasPOP3orIMAP. Youcandefineasmanyportsasyouwant.Whenyouinitiallyinstalltheserver,ithasan HTTPportat5555.
22
Note: Whenyouinstalltheserver,italsodefinesaporttypeof webMethods/Diagnosticat9999.ThediagnosticportusestheHTTPprotocoland providesyouaccesstotheIntegrationServerwhenitisunresponsive.Formore informationaboutthediagnosticport,seeAppendix C,DiagnosingtheIntegration Server. The Server Listens for Requests on Ports that You Specify
webMethods Integration Server HTTP requests
HTTP Port
HTTPS requests
HTTPS Port
FTP requests
FTP Port
FTPS requests FTPS Port Email message
IMAP or POP3 Server
Email Port
File System
File Polling Port
TheremaybetimeswhenyouwanttousethestandardportnumbersusedbyWeb servers:port80forHTTPrequestsandport443forHTTPSrequests.IfyourIntegration ServerrunsonaWindowssystem,thisisnotaproblem.However,ifyourIntegration ServerrunsonaUNIXsystem,usingaportnumberbelow1024requiresthattheserver runasroot.Forsecurityreasons,Software AGdiscouragesthispractice.Instead,run yourIntegrationServerusinganunprivilegeduserIDonahighnumberport(for example1024orabove)andusetheportremappingcapabilitiespresentinmostfirewalls tomoverequeststothehighernumberedports.
23
Services
Clientrequestsinvolveexecutingoneormoreservices.Theservermaintainssuccessfully loadedservicesasrunnableobjectswithintheserversprogramspace. Whenyouinitializetheserver,theserverloadstheservicesthatarecontainedinenabled packagesintomemory.Whenyouoranotheradministratorenableadisabledpackage, theserverloadsservicesthatareinthatpackage. Services Execute within the Integration Servers Virtual Machine
webMethods Integration Server HTTP Port Service A
HTTPS Port
Service B
FTP Port
Service C
FTPS Port
Service D
Email Port
Service E
File Polling Port
Service F
Whenaclientinvokesaservice,thatservicerunsasathreadwithintheIntegration Serverprogram.Dependingonwhatfunctiontheserviceistoaccomplish,itcanalso createadditionalthreadstoperformtaskssimultaneously.
24
Retrieving Data for Services

Tasksthatservicesperformoftenincluderetrievingdatafromdatasources.Theserver canretrievedata(forexample,XMLandHTMLdata)fromlocaldatasourcesorby issuingHTTP,HTTPS,FTP,FTPS,email,orfilepollingrequeststoresourcessuchasWeb serversandJDBCenableddatabases. ThereareanumberofmethodsyoucanusetosendfilesfromaclienttotheIntegration Server.TheIntegrationServerprovidesthefollowingautomatedmechanisms: PostafiletoaserviceviaHTTPorHTTPS. FTPafiletoaservice. Submitafiletoaserviceviaafilepollingport. Emailafiletoaserviceasanattachment. Note: IfyouuseTradingNetworks,youcansendsomefiles,specificallyflatfiles, directlytoTradingNetworks.FormoreinformationabouthowTradingNetworks processesflatfiles,seetheDefiningandManagingFlatFileDocumentTypes chapterinwebMethodsTradingNetworksAdministratorsGuide. WhenaclientsubmitsafiletotheIntegrationServer,theserverusestheappropriate contenthandlertoparsethecontentsofthefileandpassthemtothetargetservice. Note: IfanFTPorFTPSportreceivesafilethatdoesnothaveanextension,the IntegrationServerwillcallthedefaultcontenthandler. Foralltransmissionmethodsexceptthefilepolling,theclientspecifiestheservicetobe executed.Forfilepolling,theserveralwaysexecutestheserviceassociatedwiththefile pollingport. FormoreinformationaboutusingsendingandreceivingXMLfiles,seetheXMLServices DevelopersGuide.Formoreinformationaboutsendingandreceivingflatfiles,seeFlatFile SchemaDevelopersGuide.YoucanalsorefertothewebMethodsIntegrationServerBuiltIn ServicesReferenceforinformationaboutservicesyoucaninvokefromtheserviceyou write. Whentheserveraccessesdatafromexternaldatasources,youcanoptionallyrouteeither protocol(HTTPorHTTPS)throughaproxyserver.
25
The Server Gets Data from Local Resources or Resources on the Internet
Local Data Source
optional Proxy Server HTTP requests
HTTP Port HTTPS Port
Service A
Proxy Server Internet
HTTPS requests
Service B
FTP Port
Service C
IMAP or POP3 Server
Email Port
Service D
File System
File Polling Port
Service E
How the Server Executes Services

WhentheIntegrationServerreceivesarequestfromaclient,itperformsthefollowing actions: 1 2 3 4 5 Theserverauthenticatestheclient. Ifasessionalreadyexistsfortheclient,theserverusestheexistingsession.Ifone doesnotexist,theservercreatesasession. Theserverdeterminesthecontenttypeoftheservicerequestsoitcanpreparedata fortherequestedservice. Theserverusesthesuppliedservicenametolookuptheservice. Theserverdetermineswhetheraccesstotherequestedserviceisbeingcontrolled basedontheportonwhichtherequestcamein.Ifthereisnorestriction,theserver continueswiththeexecutionoftheservice. UsingtheACL,theserverlooksuptheAccessControlList(ACL)fortheserviceand determineswhethertheclientistobegrantedaccesstotheservice.IftheACL
26
indicatesthattheclientisallowedtoaccesstheservice,theservercontinueswiththe executionoftheservice. 7 8 9 Ifauditingisenabled,theserveraddsanentrytotheAuditLogtomarkthestartof therequest. Theserverstartsgatheringservicestatisticsfortheservice. Theservercheckstoseeiftheresultsforthisservicearecached.Ifservicesarecached, theserverreturnsthecachedresults.Ifservicesarenotcached,theserverinvokesthe service.Iftheserviceisaflowservice,whichcanconsistofseveralservices,itinvokes eachserviceintheflow. Note: Foreachserviceinaflow,theserverperformssteps6through11. 10 Theserverendsthegatheringofserverstatisticsfortheservice. 11 Ifauditingisenabled,theserveraddsanentrytotheAuditLogtomarktheendof therequest. 12 Theserverencodestheserviceresultsasspecifiedbythecontenttype. 13 Theserverreturnstheresultstotheclient.
Security Features
TheIntegrationServerhasseveralbuiltinsecuritymechanismstoprotectservicesfrom unauthorizedaccess,preventunauthorizedadministrationoftheIntegrationServer,and topreventdatafrombeinginterceptedduringtransmission. Itrequiresclientstopresentvalidcredentials(i.e.,usernameandpasswordoraclient certificate)inordertoconnecttotheserver. Itcontrolsaccesstoindividualservicesbyusergroups.Thismechanismisprovided throughtheuseofAccessControlLists(ACLs)thatyouassociatewithaservice.For thegreatestsecurity,associateallserviceswithanACL. Itallowsyoutocontrolaccesstoservicesbasedontheportonwhichaservicerequest isreceived. Itrequiresclientstopresentvalidusernames(withpasswords)thathave AdministratorprivilegesbeforeallowingaccesstothewebMethodsIntegration ServerAdministratorfunctions. Ithashesuserpasswordsbeforestoringthem. ItsupportsencryptedconversationsthroughSecureSocketsLayer(SSL). ItallowsyourIntegrationServertopresentdifferentclientcertificatestodifferentSSL servers. Foradditionalinformationabouttheserverssecurityfeatures,refertoChapter 10, ManagingServerSecurity.
27
ThesecurityoftheIntegrationServerdependsonthesecurityoftheunderlying operatingsystem.Makesureyoudothefollowing: Followallvendorrecommendationsfortightconfiguration Removeanyunnecessarynetworkservices,suchastelnetormail,incasetheycontain securityflaws. Regularlycheckforandinstallpatchesfromthevendorthatmightaffectsecurity. Seeyouroperatingsystemsdocumentationforinstructionsonaccomplishingthese tasks.
Logging
Loggingfortheplatformprovidesimportantdatayouneedtomonitorplatformactivity andcorrectproblems.TheIntegrationServermaintainsthisloggingdata.Forcomplete informationandinstructionsaboutworkingwithloggingdata,seethewebMethods LoggingGuide.
Caching
Cachingisanoptimizationfeaturethatcanimprovetheperformanceofservices.You activateitonaservicebyservicebasis.Whenyouenablecaching,theserversavesthe serviceinvocationresultsinalocalcacheforaspecifiedperiodoftime.Whiletheresults areincache,ratherthanreinvokingtheservice,theservercanquicklyretrievethe serviceresultsforsubsequentclientsrequestsfortheservice. Cachingcansignificantlyimproveresponsetimeofservicesthatretrieveinformation frombusydatasourcessuchashightrafficcommercialWebserversordatabases. Foradditionalinformationaboutusingcache,seeChapter 19,CachingServiceResults.
28
Starting and Stopping the Server

30 33 36 37 38 38
Starting the webMethods Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing Whether the Integration Server is a Windows Application or Windows Service . . . . . What Happens When You Start the Server? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Shutting Down the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Restarting the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Server Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
29
3 Starting and Stopping the Server
Starting the webMethods Integration Server

ThewebMethodsIntegrationServermustberunninginorderforclientstoexecute services.Ifyouareusingtheserverinadevelopmentenvironment,itmustberunningin orderforyourdeveloperstobuild,update,andtestservicesusingthewebMethods Developer. To start the Integration Server on Windows 1 2 3 ClickStart. IntheProgrammenupointtothewebMethodsfolder,thenpointtotheServersfolder. ClicktheIntegration Servericon. To start the Integration Server on UNIX 1 2 Locatetheserver.shscriptfilethatyoumodifiedforyourenvironmentwhenyou installedtheserver. Executethisscript. Note: Runthisscriptwhenloggedinasanonrootuser.Runningthescriptasroot mightreducethesecurityofyoursystem. TheservercanconsumemorefilesandsocketsonaUNIXsystemthanonother systems.Therefore,ifyouarerunningtheserveronaUNIXsystem,Software AG recommendsthatrunitwithatleast102filedescriptors.Youcanincreasethenumber ofavailablefiledescriptorsbyenteringthefollowingcommandfromtheUNIX commandlinebeforestartingtheserver:
ulimit -n number
Note: IfyourIntegrationServerhasbeenconfiguredtorequestamasterpasswordfor outboundpasswordencryption,youwillbepromptedforthispasswordinapopup windoworfromtheserverconsole.RefertoManagingOutboundPasswordson page 242formoreinformationaboutthispassword.
30
Starting the Server from the Command Line

Therearetimeswhenitisusefultostarttheserverfromthecommandline.Startingthe serverthiswayallowsyoutooverridecertainsettingsintheconfigurationfile.Italsolets youstarttheserverindebugmode,soyoucanrecordordisplayserveractivity. 1 Atacommandline,typethefollowingcommandtoswitchtotheservershome directory:
cd IntegrationServer_directory
Typethefollowingcommandtostarttheserver: ForWindows: bin\server.bat switch switch ForUNIX:

bin/server.sh switch switch
whereswitchisanyofthefollowing: switch
-port portNumber
Description SpecifiestheportonwhichtheserverlistensforHTTP requests.

portNumberspecifiestheTCP/IPportnumber
Example:-port 8080 Thisswitchoverridesthevalueassignedto watt.server.port. Note: Touseport80(thestandardforHTTP)orport443 (thestandardforHTTPS),UNIXusersmustberunningas root.Forsecurityreasons,abettermethodistousea highernumberport(5555forHTTPand8080forHTTPS), andifnecessaryhavethefirewallremapport80tothe desiredport.SeeArchitectureonpage 22foradiscussion ofremappingports.
-home directoryName
Specifiestheservershomedirectory.
directoryNamespecifiesthecompletepathforthehome
directory. Example:-home D:\wmtest\server Thisswitchoverridesthevalueassignedto

watt.server.home. -debug level
Specifiesthelevelofdetailyouwanttheservertomaintain initsserverlogforthissession.
levelindicatesthelevelofdetailyouwanttorecordinthe
log.
31
switch
Description Specify... Fatal Error Warn Info Debug Trace To record... Fatalmessagesonly. Errorandfatalmessages. Warning,error,andfatalmessages. Informational,warning,error,andfatal messages. Debug,informational,warning,error,andfatal messages. Trace,debug,informational,warning,error, andfatalmessages.
Forthissession,thisswitchoverridesthevaluespecified fortheDefaultfacilityontheSettings > Loggingpageand assignedtowatt.debug.level. Note: PriortoIntegrationServer7.1,IntegrationServerused anumberbasedsystemtosetthelevelofdebug informationwrittentotheserverlog.IntegrationServer maintainsbackwardcompatibilitywiththissystem.For moreinformationaboutthenumberbasedlogginglevels, seethedescriptionofthewatt.debug.level propertyin Appendix B,ServerConfigurationParameters.
-log destination
Specifieswhereyouwanttheservertowriteitsserverlog informationforthissession.Specifyoneofthefollowing fordestination: Option

filename
Description Specifythefullyqualifiedpathtothefilein whichyouwanttheservertowriteserverlog informationforthissession.Thedefaultis serveryyyymmdd.log. Displayserverloginformationonthe computerscreen.Whenyouusethisoption, theserverrecordsatimestampinthejournal logfile,butdoesnotrecordanyotherlog informationinthefile.
none
Thisswitchoverridesthevalueassignedto watt.debug.logfileforthissession.
32
Changing Whether the Integration Server is a Windows Application or Windows Service

TheIntegrationServercanrunaseitheraWindowsapplicationoraWindowsservice. Use a Windows applicationifyouwanttocontrolwhentheIntegrationServerinitializes. WhentheIntegrationServerisaWindowsapplication,youmustmanuallystartit. IfyouinstalledtheIntegrationServerasaWindowsserviceandnowwantittobea Windowsapplication,youcanmanuallyremovetheWindowsserviceforthe IntegrationServer.AfterremovingtheWindowsservice,theIntegrationServerwill stillbeavailableasaWindowsapplication.SeeSwitchingtheServerfroma WindowsServicetoaWindowsApplicationonpage 34. Use a Windows servicetohavetheIntegrationServerautomaticallyinitializewhenthe machineonwhichitisinstalledinitializes.WhenyouuseaWindowservice,youdo nothavetomanuallyrestarttheIntegrationServerfollowingamachinerestart. IfyouinstalledtheIntegrationServerasaWindowsapplicationandnowwantitto beaWindowsservice,youcanmanuallyregistertheIntegrationServerservice.See SwitchingtheServerfromaWindowsApplicationtoaWindowsServiceon page 34. Note: IfyouwanttheIntegrationServertopromptforthemasterpasswordfor outboundpasswordsatserverinitialization,donotrunitasaWindowsservice. Formoreinformationaboutoutboundpasswordsandthemasterpassword,refer toChapter 16,OutboundPasswords.
33
Switching the Server from a Windows Service to a Windows Application

IfIntegrationServerwasinstalledasaWindowsservice,andyouwantIntegration ServertorunasaWindowsapplication,youmustremovetheWindowsserviceforthe IntegrationServer. To manually remove the Windows service for the Integration Server 1 IftheWindowsserviceisrunning,stopit.YoucanstoptheWindowsservicebyeither usingtheIntegrationServerAdministratortoshutdowntheIntegrationServeror fromtheServices dialogboxintheMicrosoftWindowsControlPanel. Openacommandwindow,navigatetotheIntegration Server_directory\support\win32directoryandrunthiscommand:
installSvc.bat unreg
Note: IfyouarerunningtheWindowsVistaoperatingsystemwiththeUser AccountControlsecurityfeatureenabled,thecommandpromptyouusetorun theinstallSvc.batservicemustbelaunchedwithfullAdministratorprivileges.To launchthecommandpromptwithfullAdministratorprivileges,navigatetoAll Programs>Accessories,rightclickontheCommandPromptlisting,andselectthe Run as Administratoroption.Ifyouarenotloggedintotheoperatingsystemwith Administratorprivileges,youwillbepromptedtosupplyAdministrator credentials.
Switching the Server from a Windows Application to a Windows Service

UsethefollowingproceduretoregistertheIntegrationServerasaWindowsservice. Note: TheuserwhoseidentitywillbeusedtoruntheIntegrationServerasaWindows servicemusthavePowerUserprivileges. To manually register the Integration Server to run as a Windows service 1 Edittheserver.batfiletofityourenvironment.Forexample,youmightchangethe Javaminimumandmaximumheapsize.Theserver.bat scriptfileislocatedinthe IntegrationServer_directory\bindirectory. EdittheinstallSvc.batfilelocatedintheIntegrationServer_directory\support\win32 directory.Usingatexteditor,opentheinstallSvc.batfileandeditthefollowing linesofcode:
SET SVCNAME="wmIS" SET DISPLAYNAME="webMethods Integration Server 6.5" SET DESCRIPTION="webMethods Integration Server 6.5"
34
TheSVCNAMEvalueisthenameoftheserviceandmustbeauniquevalueonyour system. TheDISPLAYNAMEvalueisusedbyMicrosoftWindowstolisttheserviceonthe WindowsServicesControlPanelandmustuniquelyidentifytheservice. TheDESCRIPTIONvaluedescribestheservice. 3 Openacommandwindow,navigatetotheIntegration Server_directory\support\win32directoryandruninstallSvc.battocreatethe IntegrationServerservice. Note: IfyouarerunningtheWindowsVistaoperatingsystemwiththeUser AccountControlsecurityfeatureenabled,thecommandpromptyouusetorun theinstallSvc.batservicemustbelaunchedwithfullAdministratorprivileges.To launchthecommandpromptwithfullAdministratorprivileges,navigatetoAll Programs>Accessories,rightclickontheCommandPromptlisting,andselectthe Run as Administratoroption.Ifyouarenotloggedintotheoperatingsystemwith Administratorprivileges,youwillbepromptedtosupplyAdministrator credentials. IntheMicrosoftWindowsControlPanelintheServicesdialogbox,verifythatthe IntegrationServercreatedtheservicewiththespecifieddisplayname. 4 Starttheservicefromoneofthefollowingplaces: Services dialogboxintheMicrosoftWindowsControlPanel,or Commandlineusingthefollowingcommand:
net start <SVCNAME>Inthisexample,youwouldtypenet start wmIS
To configure multiple Integration Servers to run as Windows services on a Windows machine InadditiontorunninganIntegrationServerasaWindowsservice,youcanalso configuremultipleIntegrationServersofthesameversiontorunasWindowsserviceson asingleWindowsmachine. 1 ToconfigureanIntegrationServerfromanotherinstallationonthesamemachineto runasaWindowsservice,refertoandrepeatsteps1through4inTomanually registertheIntegrationServertorunasaWindowsserviceonpage 34. Instep2,givetheserviceauniqueservicenameanddisplaynamethatisdifferent fromtheoriginalWindowsservicethatyouconfigured.Todoso,gotothe IntegrationServer_directory\support\Win32directoryandopentheinstallSvc.batfile. SettheSETSVCNAMEandSETDISPLAYNAMEparameterstouniquevalues.You mightalsowanttosettheSETDESCRIPTIONparameter.
35
What Happens When You Start the Server?

WhenyoustarttheIntegrationServer,itperformsaseriesofinitializationstepstomake itselfreadyforclientrequests.Theserver: 1 2 3 Establishestheoperatingenvironmentbyusingtheconfigurationparameterslocated intheconfigurationfile(IntegrationServer_directory\config\server.cnf). Initializesprocessesthatperforminternalmanagement. Loadsinformationaboutalltheenabledpackagesandtheirservicesthatresideinthe webMethods_directory\packagesdirectory.Ifapackagedependsonotherpackages, theserverloadstheprerequisitepackagesfirst.Theserverdoesnotloaddisabled packages. Executesthestartupservicesforeachloadedpackage. Initializestheguaranteeddeliveryengine.Theserverchecksthejobstoreforpending guaranteeddeliverytransactions.Itretriesthependingtransactionsasthe guaranteeddeliveryconfigurationsettingsspecify.Formoreinformation,referto Chapter 20,ConfiguringGuaranteedDelivery. Schedulesinternalsystemtasks.
4 5
How to Tell if the Server Is Running Correctly

Todeterminewhetheryourserverisrunning,startyourbrowserandpointittothe IntegrationServer.(SeeStartingtheIntegrationServerAdministratoronpage 42ifyou needinstructionsforthisstep.) Iftheserverisrunning,youwillbepromptedforanameandpassword. Iftheserverisnotrunning,yourbrowserwillissueanerrormessagesimilartothe following:
Cannot open the Internet site http://localhost:5555. A connection with the server could not be established.
IftheIntegrationServerdetectsaproblemwiththemasterpasswordoroutbound passwordsatstartup,itwillplaceyouinsafemode,whichisaspecialmodefromwhich youcandiagnoseandcorrectproblems.WhentheIntegrationServerisinsafemode,it displaystheIntegrationServerAdministrator,buttheIntegrationServerisnotconnected toanyexternalresources. Whenyouareplacedintosafemodebecauseofproblemswiththemasterpasswordor outboundpasswords,youwillseethefollowingmessageintheupperleftcornerofthe ServerStatisticsscreenoftheIntegrationServerAdministrator:

SERVER IS RUNNING IN SAFE MODE. Master password sanity check failed -- invalid master password provided.
Theseproblemscanbecausedbyacorruptedmasterpasswordfile,acorrupted outboundpasswordfile,orbysimplymistypingthemasterpasswordwhenyouare promptedforit.Ifyoususpectyouhavemistypedthepassword,shutdowntheserver
36
andrestartit,thistimeenteringthecorrectpassword.Ifthisdoesnotcorrecttheproblem, refertoWhenThereAreProblemswiththeMasterPasswordorOutboundPasswords atStartuponpage 248forinstructions.
Shutting Down the Integration Server

ShutdowntheservertostoptheIntegrationServerandallactivesessions. To shut down the server 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheupperrightcornerofanyIntegrationServerAdministratorscreen,click Shutdown and Restart. Selectwhetheryouwanttheservertowaitbeforeshuttingdownortoshutdown immediately. Delay number minutes or until all client sessions are complete. Specifythenumberof minutesyouwanttheIntegrationServertowaitbeforeshuttingdown.Itthenbegins monitoringuseractivityandautomaticallyshutsdownwhenallnonadministrator sessionscompleteorwhenthetimeyouspecifyelapses(whichevercomesfirst). Perform action immediately.Theserverandallactivesessionsterminateimmediately. 4 5 Forinstructionsonhowtoviewtheactivesessions,refertoViewingActive Sessionsonpage 37. ClickShutdown.
Viewing Active Sessions

Beforeyoushutdownorrestarttheserver,youcanviewthesessionsthatarecurrently active. To view active sessions 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheServermenuoftheNavigationpanel,clickStatistics. Clickonthecurrentnumberofsessions.
37
Restarting the Integration Server

RestarttheserverwhenyouneedtostopandreloadtheIntegrationServer.Youshould restarttheserverwhen: You make certain configuration changes.Someconfigurationchangesrequiretheserverto berestartedbeforetheytakeeffect.Thisdocumentindicateswhenyouarerequiredto restarttheserverforconfigurationchanges. You want to incorporate updated services that cannot be dynamically reloaded. Thistypically occursfornonJavaservices. To restart the server 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheupperrightcornerofanyIntegrationServerAdministratorscreen,click Shutdown and Restart. Selectwhetheryouwanttheservertowaitbeforerestartingortorestartimmediately. Delay number minutes or until all client sessions are complete. Specifythenumberof minutesyouwanttheIntegrationServertowaitbeforerestarting.Itthenbegins monitoringuseractivityandautomaticallyrestartswhenallnonadministrator sessionscompleteorwhenthetimeyouspecifyelapses(whichevercomesfirst). Perform action immediately.Theserverandallactivesessionsterminateimmediately. Thentheserverrestarts. Forinstructionsonhowtoviewtheactivesessions,refertoViewingActive Sessionsonpage 37. 4 ClickRestart.
Server Recovery
IfahardwareorsoftwareproblemcausestheIntegrationServertofail,restarttheserver usingthenormalstartupprocedure.Theserverwillattempttoperformcleanupand initializationprocessestoresettheoperatingenvironment. Aspartoftherecoveryprocess,theserverautomatically: Reloadsthecacheenvironmenttoitsprefailurestate. Restoresthetransactionmanagersguaranteeddeliveryqueues.SeeConfiguring GuaranteedDeliveryonpage 323foradditionalinformationaboutguaranteed deliveryrecoveryoptions.
38
Servicesthatyoursitehascreatedmighthavetheirownuniquerecoveryrequirements. Consultwithyourdevelopersforinformationabouttheserequirements. Somecircumstancesmightrequiremanualinterventiontorestarttheserver.Seebelow. Tip! BeforerestartingIntegrationServer,youcancollectdiagnosticdatato troubleshootruntimeissues.Forinformationaboutusingthediagnosticportand utility,seeAppendix C,DiagnosingtheIntegrationServer.Alsorefertothis chapterforinformationongeneratingthreaddumptotroubleshootreasonsforserver slowdownorunresponsiveness.
Integration Server Data Integrity and Recoverability Considerations

ThewebMethodsIntegrationServerutilizesawebMethodsphysicalstoragetechnology topersistcriticaloperationaldata.Thisstoragetechnologyemploysdatabaselike technologyofloggingandtransactionalmanagement.Undernormaloperationsthese facilitiesmaintaintheintegrity,consistency,andrecoverabilityofdatapersistedtothese files.However,evenwiththesesafeguards,abnormalservershutdownandcatastrophic failurescanoccur,whichcouldresultinthesefilesbeingleftinanunrecoverablestate. ShuttingdowntheIntegrationServerbyanymeansotherthantheAdministrationUser Interfacemayresultincriticaldatafilesbeingleftinanunrecoverablestate.Thiswill resultintheinabilitytorestarttheIntegrationServerwithoutmanualinterventionto removeorrecoverthedamageddatafiles. Important! Establishsitespecificbackupandrestoreprocedurestoprotectthesecritical datafiles ThemissioncriticalnatureofthedatastoredintheIntegrationServersdatafiles requiresthatitbebackedupperiodicallyfordisasterrecovery.Asinallcriticaldata resources,thepotentialexistsforaphysicalfailuretoleavetheIntegrationServerdata filesinacorruptedstate.Inthesesituationsthemethodofrecoveryistoreplacethese datafileswiththemostcurrentbackup.Thefrequencyandnatureofthesebackups dependsonthecriticalnatureofthedatabeingstored.Backupsofthesedatafilesshould beanofflineprocesswiththeIntegrationServerinanidleorshutdownstate,i.e.nodisk activity. Important! Implementsitespecificprocedurestoperiodicallybackupthecritical IntegrationServerdatafiles.Youcanuseanyfilesystembackuputility.Performthe backupprocessonlywhentheIntegrationServerisshutdownorinaquiescestate, (nodiskactivity).Thisrestrictionensuresthatthebackupwillcapturethesecritical datafilesinaconsistentstate.BackingupanactiveIntegrationServermayresultin capturingasnapshotofthedatafilesthatareinaninconsistentstateandtherefore unusableforrecoverypurposes
39
Critical Integration Server Data Files

TherearefoursubdirectoriesintheIntegrationServerscurrentlyworkingdirectorythat containcriticaldatafilesthatmustbebackedupforrecoverypurposes.These subdirectoriesare: ./audit/data Thefilesinthissubdirectorycontainauditevents,generatedbytheIntegration Server,thathaveyettobepersistedintheauditdatabaseorfilesystem.Lossofthese fileswillresultinthelossofallpendingauditevents.Withoutthesefiles,recovery frombackupsmayresultinduplicateeventsbeingstoredintheauditdatabaseorfile system.Backupthesetwofiles: AuditStore.data0000000 AuditStore.log0000000 ./DocumentStore Thefilesinthissubdirectorycontainthelocallypersisteddocumentsbeingprocessed bytheIntegrationServer.Thelossofthesefileswillresultinthelossofanypersisted documents.Backupthesesixfiles: ISResubmitStoredata0000000 ISResubmitStorelog0000000 ISTransStoredata0000000 ISTransStorelog0000000 TriggerStoredata0000000 TriggerStorelog0000000 ./WmRepository4 ThefilesinthissubdirectorycontainmetadatafortheIntegrationServer.Thelossof thesefilescouldresultinlossofconfigurationinformationandmayrequiremanual reconfiguration.Backupthesetwofiles: FSDdata0000000 FSDlog0000000
40
Using the Integration Server Administrator

42 42 43 44
What Is the Integration Server Administrator? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Starting the Integration Server Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Basic Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
41
4 Using the Integration Server Administrator
What Is the Integration Server Administrator?

TheIntegrationServerAdministratorisanHTMLbasedutilityyouusetoadministerthe webMethodsIntegrationServer.Itallowsyoutomonitorserveractivity,manageuser accounts,makeperformanceadjustments,andsetoperatingparameters. YoucanruntheIntegrationServerAdministratorfromanybrowserequipped workstationonyournetwork.(TheIntegrationServerAdministratorisabrowserbased applicationthatusesservicestoaccomplishitswork.)
Starting the Integration Server Administrator

TousetheIntegrationServerAdministrator,simplyopenyourbrowserandpointitto theportonthehostmachinewheretheIntegrationServerisrunning. Important! TheIntegrationServermustberunninginordertousethisutility.Ifthe serverisnotrunning,yourbrowserwillissueanerrorsimilartothefollowing:
Cannot open the Internet site http://localhost:5555. A connection with the server could not be established.
To start the Integration Server Administrator 1 2 Startyourbrowser. PointyourbrowsertothehostandportwheretheIntegrationServerisrunning. Examples Iftheserverwererunningonthedefaultportonthesamemachinewhereyouare runningtheIntegrationServerAdministrator,youwouldtype:
http://localhost:5555
Iftheserverwererunningonport4040onamachinecalledQUICKSILVER,you wouldtype:
http://QUICKSILVER:4040
Logontotheserverwithausernameandpasswordthathasadministrator privileges. IfyoujustinstalledtheIntegrationServer,youcanusethefollowingdefaultvalues: UserName: Password: Administrator manage
Important! Usetheexactcombinationofupperandlowercasecharactersshown above;usernamesandpasswordsarecasesensitive.
42
Ifyouchangethepassword,besuretoselectonethatisdifficulttoguess.Forexample, useamixtureofupperandlowercaseletters,numbers,andspecialcharacters.Donot useaname,phonenumber,socialsecuritynumber,licenseplateorothergenerally availableinformation.
Basic Operation
WhenyoustarttheIntegrationServerAdministrator,yourbrowserdisplaystheStatistics screen. The Integration Server Administrator Screen
TheNavigationpanelontheleftsideofthescreendisplaysthenamesofmenusfrom whichyoucanselectatask.Tostartatask,clickatasknameintheNavigationpanel.The serverdisplaysascreenthatcorrespondstothetaskyouselect.
Getting Help
YoucanobtaininformationabouttheIntegrationServerAdministratorbyclickingthe HelplinkintheupperrightcornerofanyIntegrationServerAdministratorscreen.The helpsystemdisplaysadescriptionoftheparametersforthescreenandalistof proceduresyoucanperformfromthescreen.Fromthiswindow,clickShow Navigation Area toviewthehelpsystemstableofcontentsfromwhichyoucansearchforaspecific procedureorscreendescription.
43
The Configuration File

ConfigurationsettingsfortheIntegrationServerarestoredintheserverconfiguration file(server.cnf).ThisfileresidesintheIntegrationServer_directory\configdirectoryand containsparametersthatdeterminehowtheserveroperates. Typically,youwillusetheIntegrationServerAdministratortosetparametersinthe server.cnffile,buttheremaybetimeswhenyouneedtoeditthefiledirectlywithatext editor. Foralistofparametersintheserver.cnffileandtheirdefaultvalues,seeAppendix B, ServerConfigurationParameters.
44
Managing Users and Groups

46 47 52 54
Users and Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining a User Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disabling and Enabling Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
45
5 Managing Users and Groups
Users and Groups

UsetheIntegrationServerAdministratortodefineuserandgroupinformationtothe server.Thedefinitionforausercontainstheusername,password,andgroup membership.Thedefinitionforagroupcontainsthegroupnameandalistofusersinthe group.Theserverstoresandmaintainstheinformation. Alternatively,youcansetupthewebMethodsIntegrationServertoaccessthe informationfromanexternaldirectoryifyoursiteusesoneofthefollowingexternal directoriesforuserandgroupinformation: Centralusermanagement LightweightDirectoryAccessProtocol(LDAP) ThischapterdescribesonlyhowtheIntegrationServerworkswhenuserandgroup informationisdefinedinternally.Forinformationaboutusinganexternaldirectorywith theIntegrationServer,seeChapter 17,ConfiguringaCentralUserDirectoryorLDAP.
Purpose of Users and Groups

Theserverusesuserandgroupinformationtoauthenticateclientsanddeterminethe serverresourcesthataclientisallowedtoaccess. Iftheserverisusingbasicauthentication(usernamesandpasswords)toauthenticatea client,itusestheusernamesandpasswordsdefinedinuseraccountstovalidatethe credentialsaclientsupplies. Afteraclientisauthenticated(whetherthroughbasicauthenticationorclient certificates),theserverusesthegroupmembershiptodetermineifaclientisauthorized fortherequestedaction,suchas,usingtheIntegrationServerAdministratororinvoking aservice. Accesstotheserversresourcesiscontrolledatthegrouplevel.Bysettingupusersand groups,youcancontrolwhocan: Configure and manage the server. OnlyusersthataremembersoftheAdministrators group(administratorprivilege)canaccesstheIntegrationServerAdministrator. Create, modify, and delete services that reside on the server.Onlyusersthataremembersof theDevelopersgroup(developerprivileges)canconnecttotheserverfromthe webMethodsDeveloper. Access services and files that reside on the server.Accesstoservicesandfilesisprotected atthegrouplevel.
46
Defining a User Account

WhenyoucreateauseraccountontheIntegrationServer,youspecifyausername, password,andgroupmembership. User name.Ausernameisauniquenamethatidentifiesaclient.Youcanspecifya usernamethatrepresentsanactualperson(e.g.,JDSmithforJohnD.Smith),oryou canspecifyausernametorepresentapplications,jobfunctions,ororganizations.For example,youmightsetupgenericallynamedusernamessuchas MktgPurchAgent,MktgTimeKeeper,andsoforth,torepresentjobfunctions. Password.Apasswordisanarbitrarystringofcharactersthatyouassociatewitha username.Theserverusesthepasswordwhenauthenticatingaclientwhohas submittedavalidusername.Formoreinformationaboutauthentication,see Chapter 13,AuthenticatingClients. Apasswordismeanttobeasecretcodesharedonlybytheserver,theserver administrator,andtheowneroftheuseraccount.Itspurposeistogivetheserver addedassurancethatarequestiscomingfromalegitimateuser.Onlyadministrators canassignapasswordtoausernameandchangeapasswordforanexistingaccount. Foradditionalsecurity,theserverhashespasswordsbeforestoringthem. Group membership.Thegroupmembershipidentifiesthegroupstowhichauser belongs.Accesstotheserversresourcesiscontrolledatthegrouplevel: OnlyusersthataremembersoftheAdministratorsgroupcanconfigureandmanage theserverusingtheIntegrationServerAdministrator.Formoreinformationabout controllingaccesstotheIntegrationServerAdministrator,seeSettingUp Administratorsonpage 141. OnlyusersthataremembersoftheDevelopersgroupcanconnecttotheserverfrom thewebMethodsDevelopertocreate,modify,anddeleteservices.Forinformation, seeSettingUpDevelopersonpage 142. TheserverprotectsaccesstoservicesandfilesusingAccessControlLists(ACLs).You setupACLsthatidentifygroupsthatareallowedornotallowedtoaccessaresource. Formoreinformationaboutprotectingservicesandfiles,seeControllingAccessto ResourceswithACLsonpage 168.
47
Predefined User Accounts

Theserverhasthefollowingpredefineduseraccounts: User Administrator Groups Everybody Administrators Replicators Everybody Anonymous Everybody Developers Everybody Replicators Description Auseraccountthathasadministratorprivileges. YoucanusetheAdministratoruseraccountto accesstheIntegrationServerAdministratorto configureandmanagetheserver. Theserverusestheinformationdefinedforthe Defaultuserwhentheclientdoesnotsupplyauser nameandpassword. Auserthatcanconnecttotheserverfromthe webMethodsDevelopertocreate,modify,and deleteservicesthatresideontheserver. Theuseraccountthattheserverusesduring packagereplication.Formoreinformationabout packagereplication,seeCopyingPackagesfrom OneServertoAnotheronpage 292.
Default
Developer
Replicator
Adding User Accounts

Usethefollowingproceduretoaddauseraccountforauser. To add a user account to the server 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickUser Management. ClickAdd and Remove Users. IntheCreate Userssectionofthescreen,specifythefollowinginformation: For this parameter User Names Specify Auniqueusernamemadeupofacombinationofletters, numbers,orsymbols.Youcanspecifyoneusernameorone username;passwordcombinationperline.PressENTERto separatethelines. Important! Usernamesarecasesensitive.Whenyoucreatea useraccount,typeitexactlyasyouwanttheclienttoenterit.
48
For this parameter Password
Specify Apasswordmadeupofacombinationofletters,numbers,or symbols.YoucanspecifythepasswordintheUser Names fieldbyenteringusername;passwordoryoucanenterthe passwordinthisfield.Ifyoudonotspecifyapasswordinthe User Names field,theserverusesthepasswordspecifiedin thisfieldfortheuser.Ifyouspecifymultipleuserswithout passwordsintheUser Namesfield,theserverusesthe passwordinthePasswordfieldasthepasswordforthose users. Apasswordisrequired. Important! Passwordsarecasesensitive.Typethesevalues exactlyasyouwanttheclienttoenterit. Besuretoselectpasswordsthataredifficulttoguess.For example,useamixtureofupperandlowercaseletters, numbers,andspecialcharacters.Donotuseaname,phone number,socialsecuritynumber,licenseplateorother generallyavailableinformation.
Re-Enter Password 5 ClickCreate Users.
Thesamepasswordagaintomakesureyoutypedit correctly.
Removing User Accounts

Usethefollowingproceduretodeleteauseraccountwhenitisnolongerneeded. Note: Theserverwillnotallowyoutoremovethefollowingbuiltinuseraccounts: Administrator,Default,Developer,andReplicator. To delete a user account from the server 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickUser Management. ClickAdd and Remove Users.
49
4 5
IntheRemove Userssectionofthescreen,selecttheusernamesfortheuseraccounts youwanttodelete. ClickRemove Users.Theserverissuesaprompttoverifythatyouwanttodeletethe useraccount.ClickOKtoremovetheuseraccount. Important! Whenyoudeleteauser,theuserisautomaticallyremovedfromthe memberslistsofallgroupstowhichitwasassigned.
Changing Passwords and Password Requirements

Youcanchangethepasswordforyouruseraccount.Inaddition,youcancontrolwhether usersareallowedtochangetheirpasswordsthroughtheDeveloper. Important! Donotchangeapasswordifyouareoutsideofthecorporatefirewalland youdidnotuseSSLtoconnecttotheIntegrationServer. Note: YoucannotusetheIntegrationServerAdministratororthewebMethods Developertoadministerusersorgroupsstoredinanexternaldirectory.This restrictionincludeschangingthepasswordsoftheseusers.
Password Requirements
Forsecuritypurposes,thewebMethodsIntegrationServerplaceslengthandcharacter restrictionsonpasswordsfornonadministrators.ThewebMethodsIntegrationServer containsadefaultsetofpasswordrequirements;however,youcanchangethesewiththe IntegrationServerAdministrator.Anonadministratormustobservetheserestrictions whenchangingapassword.Anadministratoruserreceivesawarningifheorshe changesapasswordtoonethatdoesnotmeettheserestrictions. ThedefaultpasswordrequirementsprovidedbywebMethodsIntegrationServerareas follows: Requirement Minimumnumberofcharacters(alphabeticcharacters,digits,andspecial characterscombined)thepasswordmustcontain. Minimumnumberofuppercasealphabeticcharactersthepasswordmust contain. Minimumnumberoflowercasealphabeticcharactersthepasswordmust contain. Default 8 2 2
50
Requirement Minimumnumberofdigitsthepasswordmustcontain. Minimumnumberofspecialcharacters,suchasasterisk(*),period(.), questionmark(?),andampersand(&)thepasswordmustcontain. Note: Apasswordcannotbeginwithanasterisk(*).
Default 1 1
Usethefollowingproceduretochangethepasswordassociatedwithausername. Important! Besuretoselectpasswordsthataredifficulttoguess.Forexample,usea mixtureofupperandlowercaseletters,numbers,andspecialcharacters.Donotuse aname,phonenumber,socialsecuritynumber,licenseplateorothergenerally availableinformation;thesecurityofyoursystemdependsonit. To change a users password 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecurity menuoftheNavigationpanel,clickUser Management. IntheUserssectionofthescreen,selecttheusernamefortheuserwhosepassword youwanttochangeandclickchange password. Enterthefollowinginformation: For this parameter New Password Specify Thenewpassword,madeupofanycombinationofletters, numbers,orsymbols. Important! Passwordsarecasesensitive.Typethisvalueexactly asyouwanttheclienttoenterit. Besuretoselectpasswordsthataredifficulttoguess.For example,useamixtureofupperandlowercaseletters, numbers,andspecialcharacters.Donotuseaname,phone number,socialsecuritynumber,licenseplateorother generallyavailableinformation. Confirm Password 5 ClickSave Password. Thesamepasswordagaintomakesureyoutypeditcorrectly.
51
Controlling password length and character requirements for non-Administrator users 1 2 3 4 5 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecurity menuoftheNavigationpanel,clickUser Management. ClickPassword Restrictions. ClickEdit Password Restrictions. Fillininformationinthefollowingfields: Field Enable Password Change? Description Whetherusersareallowedtochangetheir passwords.Theseusersmusthavedeveloper privileges. Minimumnumberofcharacters(alphabetic characters,digits,andspecialcharacters combined)thepasswordmustcontain. Minimumnumberofuppercasealphabetic charactersthepasswordmustcontain. Minimumnumberoflowercasealphabetic charactersthepasswordmustcontain. Minimumnumberofdigitsthepassword mustcontain. Minimumnumberofspecialcharacters,such asasterisk(*),period(.),questionmark(?), andampersand(&)thepasswordmust contain. Note: Apasswordcannotbeginwithan asterisk(*). Default Yes
Minimum Password Length
Minimum Number of Upper Case Characters Minimum Number of Lower Case Characters Minimum Number of Digits Minimum Number of Special Characters (neither alphabetic nor digits)
2 2 1 1
Disabling and Enabling Users

Theremaybetimeswhenyouneedtodisableauser.Doingsomakespasswordcracking attacksharderbyeliminatingwellknownusernames.Whenyoudisableauser,login attemptswiththatusernamewillfailauthenticationandberejected.Forexample,you mightdisabletheuseraccountofadeveloperwhoisonvacation,ortheaccountofa tradingpartnerwhosetradingprivilegesaresuspended.Becausetheuserhasbeen disabledratherthandeleted,youcanlaterreinstatetheaccountwithoutchangingthe passwordorresettingpermissions.
52
Fordeployment,youshoulddisabletheAdministratorusertopreventsomeonefrom tryingtoguessthepasswordandgainaccesstoyoursystem.Beforedisablingthe Administratoruser,youmustfirstcreateanotheruser,forexampleSmithAdmin,and addittotheAdministrators,Developers,andReplicatorsgroups.Thendisablethe Administratoruser.(InternalserverfunctionsthatrunastheAdministratoruser,suchas startupandshutdownservices,willstillbeabletorunasAdministrator.)Thenyoucan usetheSmithAdminusertoadministeryourIntegrationServer.
Disabling a User
Usethefollowingproceduretodisableauser. Important! BeforeyoudisabletheAdministratoruser,makesureyouhavedefined anotheruserwithadministratorprivilegessoyouarenotlockedoutoftheserver. To disable a user 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecurity menuoftheNavigationpanel,clickUser Management. ClickEnable and Disable Users. IntheEnabled Users listselect(highlight)theuserorusersyouwanttodisable. Toselectadditionaluserswithoutdeselectingcurrentlyselectedusers,pressthe CTRLkeywhileyouclickontheusersyouwanttoselect.Todeselectauser,pressthe CTRLkeywhileyouclickthecurrentlyselectedentry. 5 6 Atthebottomofthe Enabled Usersareaofthescreenclick ClickSave Changes. .
Theservermovestheselecteduserstothe Disabled Usersareaofthescreen.
Enabling a User
Usethefollowingproceduretoenableauser.Theonlytimeyouwillneedtoenablea userisifthesystemadministratorexplicitlydisabledit. To enable a user 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecurity menuoftheNavigationpanel,clickUser Management. ClickEnable and Disable Users. IntheDisabled Users listselect(highlight)theuserorusersyouwanttoenable.
53
Toselectadditionaluserswithoutdeselectingcurrentlyselectedusers,pressthe CTRLkeywhileyouclickontheusersyouwanttoselect.Todeselectauser,pressthe CTRLkeywhileyouclickthecurrentlyselectedentry. 5 6 Atthebottomofthe Disabled Usersareaofthescreenclick ClickSave Changes. . Theservermovestheselecteduserstothe Enabled Usersareaofthescreen.
Defining Groups
Agroupisanamedcollectionofusersthatshareprivileges.Theprivilegescanbe: Administratorprivileges Replicatorprivileges Developerprivileges Privilegestoinvokeaservice Privilegestoallowtheservertoservefiles PrivilegestoinvokeaserviceoraccessfilesaregrantedanddeniedbyAccessControl Lists(ACLs)thatyousetup.WhenanadministratorcreatesACLs,heorsheidentifies groupsthatareallowedtoaccessservicesandfilesandgroupsthataredeniedaccessto servicesandfiles. Administrator,replicator,anddeveloperprivilegesaretypicallygrantedbyaddinga usertotheAdministrators,Replicators,orDevelopersgroup,respectively.Alternatively, youcancreatenewgroupsandaddthemtotheallowlistsoftheAdministrators, Replicators,orDevelopersACLs. Creategroupsthatidentifygroupsofusersthatwillsharethesameprivileges.Whenyou createagroupdefinition,youspecifyagroupnameandthemembersofthegroup. Group name.Agroupnameisauniquenamethatidentifiesthegroup.Youcanuse anyname,forexample,anamethatdefinesadepartment(Marketing)orjobfunction (Programmers). Members.Listofusernamesthataremembersofthegroup.
54
Predefined Groups
Theserverisinstalledwiththefollowingpredefinedgroups. Group Name Administrators Members Administrator Description Thisgroupidentifiesusersthathaveadministrator privileges.Ausermusthaveadministrator privilegestoconfigureandmanagetheserver. Important! Membershipinthisgroupgives substantialpowertoaffecttheconfigurationofthe IntegrationServer.Usecautioninassigning membershipinthisgrouptoindividualswhocan betrustedtousetheprivilegecarefully. Anonymous Developers Default Developer Thisgroupidentifiesusersthathavenotbeen authenticated. Thisgroupidentifiesusersthathavedeveloper privileges.Ausermusthavedeveloperprivileges toconnecttotheserverfromtheDeveloper. Important! Membershipinthisgroupgives substantialpowertoaffecttheconfigurationofthe IntegrationServer.Usecautioninassigning membershipinthisgrouptoindividualswhocan betrustedtousetheprivilegecarefully. Everybody Administrator Default Developer Replicator Allusersareamemberofthisgroup.Everynew userisautomaticallyaddedtotheEverybody group.
55
Group Name Replicators
Members Administrator Replicator
Description Thisgroupidentifiesusersthathavereplicator privileges.TheReplicatorsgroupgivesits memberstheauthoritytoperformpackage replication.(Bydefault,theserverusesmembersof theReplicatorsgroupforpackagereplication.) UsersdonothavetobemembersoftheReplicators grouptoperformpackagereplication.Aslongas userisamemberofagroupthatisassignedtothe ReplicatorsACL,itcanperformpackage replication. Formoreinformationaboutpackagereplication, seeCopyingPackagesfromOneServerto Anotheronpage 292. Membershipinthisgroupgivessubstantialpower toaffecttheconfigurationoftheIntegrationServer. Usecautioninassigningmembershipinthisgroup toindividualswhocanbetrustedtousethe privilegecarefully.
Adding Groups
Usethefollowingproceduretoaddgroups. To add a new group to the server 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecurity menuoftheNavigationpanel,clickUser Management ClickAdd and Remove Groups. IntheCreate Groups areaofthescreen,typeauniquegroupnamemadeupofa combinationofletters,numbers,orsymbols.Youcanaddmorethanonegroupata timebyspecifyingmultiplelines,onegrouptoaline.PressENTERtoseparatelines. Important! Groupnamesarecasesensitive. 5 ClickCreate Groups.
56
Adding Users to a Group

Usethefollowingproceduretoadduserstoagroup. Note: YoucannotchangethemembershipoftheEverybodygroup.
To add users to a group 1 2 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecurity menuoftheNavigationpanel,clickUser Management. Theserverdisplaysthefollowingscreen.
TheGroupsareaofthescreen(ontheright)containstwolists.Users in this Group isa listofuserscurrentlyinthegroup.Remaining Usersisalistofusersnotcurrentlyinthe group. 3 4 UnderGroups,intheSelect grouplist,selectthegrouptowhichyouwanttoaddauser. IntheRemaining Userslistselect(highlight)theuserorusersyouwanttoaddtothe group. Toselectadditionaluserswithoutdeselectingcurrentlyselectedusers,pressthe CTRLkeywhileyouclickontheusersyouwanttoselect.Todeselectauser,pressthe CTRLkeywhileyouclickthecurrentlyselectedentry. 5 6 Afteryouhaveselectedalltheusersyouwanttoaddtothegroup,click Theservermovestheselecteduserstothe Users Currently in this Group list. Click Save Changes. .
57
Removing Users from a Group

Usethefollowingproceduretoremoveusersfromagroup. Note: YoucannotchangethemembershipoftheEverybodygroup.
To remove a user from a group 1 2 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecurity menuoftheNavigationpanel,clickUser Management. Theserverdisplaysthefollowingscreen.
TheGroupsareaofthescreen(ontheright)containstwolists.Users in this Group isa listofuserscurrentlyinthegroup.Remaining Usersisalistofusersnotcurrentlyinthe group. 3 4 UnderGroups,intheSelect grouplist,selectthegroupfromwhichyouwanttoremove auser. IntheUsers in this Group areaofthescreen,select(highlight)usersthatyouwantto removefromthegroup. Toselectadditionaluserswithoutdeselectingcurrentlyselectedusers,pressthe CTRLkeywhileyouclickontheusersyouwanttoselect.Todeselectauser,pressthe CTRLkeywhileyouclickthecurrentlyselectedentry. 5 Atthebottomofthe Users in this Groupareaofthescreenclick movestheselecteduserstothe Remaining Usersareaofthescreen. .Theserver
58
Viewing Group Membership

Usethefollowingproceduretoviewthemembersoragrouporchangethemembersina group. To view group membership for a group 1 2 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecurity menuoftheNavigationpanelclickUser Management. Theserverdisplaysthefollowingscreen.
TheGroupsareaofthescreen(ontheright)containstwolists.Users Currently in this Groupisalistofuserscurrentlyintheselectedgroup. Remaining Usersisalistofusers notcurrentlyintheselectedgroup. 3 4 UnderGroups,intheSelect grouplist,selectthegroupforwhichyouwanttoview membership. TheserverdisplaystheusersintheUsers in this Group list.
59
Removing Groups
Usethefollowingproceduretoremovegroupsthatyounolongerneed. Note: Youcannotdeleteanyofthefollowinggroups:Administrators,Developers, Replicators,Anonymous,andEverybody. To delete a group from the server 1 2 3 4 5 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecurity menuoftheNavigationpanel,clickUser Management. ClickAdd and Remove Groups. IntheRemove Groups areaofthescreen,selectthegroupsyouwanttoremove. ClickRemove Groups.
60
Configuring the Server

62 64 65 66 68 72 75 78 79 79 81 81 82
Viewing and Changing Licensing Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing the Server Thread Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting the Session Timeout Limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Outbound HTTP Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up Aliases for Remote Integration Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up Aliases for Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying a Third-Party Proxy Server for Outbound Requests . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Where the Integration Server Writes Logging, Status, and Other Information . . . . . Switching from the Embedded Database to an External RDBMS . . . . . . . . . . . . . . . . . . . . . . . . Working with Extended Configuration Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Character Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using a 64-bit JVM on Solaris and HP-UX Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Publishing Information about Integration Server Assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
61
6 Configuring the Server
Viewing and Changing Licensing Information

WhenyoupurchaseawebMethodsIntegrationServer,yourorganizationisgranteda licensetouseitwithaspecifiednumberofconcurrentusers(simultaneoussessions).The licenseexpiresafteratimeperiodspecifiedbyyourparticularpurchaseagreement.
The License Key

Whenyouinstalltheserver,thesetupprogramasksyoutoenteryourkey,whichisa specialcodeassociatedwithyourlicense.Afteryouenterthiscode,itisassignedtothe watt.server.keyparameterintheserver.cnffileintheIntegrationServer_directory\config directory.Ifthewatt.server.keyparameterisinadvertentlychangedordeletedorifyour licenseexpires,yourserverrevertstodemomode.Inthismode,thereareonlytwo licensedsessionsandtheserverautomaticallyshutsdown30minutesafteritisstarted.
Viewing or Changing the License Key

TovieworchangethelicensekeyforyourIntegrationServer,usetheLicensingscreenin theIntegrationServerAdministrator. To view the License Key 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickLicensing. ClickEdit License Key. To change the License Key 1 2 3 4 5 6 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickLicensing. ClickEdit License Key. TheserverdisplaystheEdit screen. TypethenewlicensekeyintheLicense Key field. ClickSave Changes. Note: TheIntegrationServerupdatestheexpirationdateautomaticallyafteryouclick Save Changes.
62
Renewal Reminders
Approximately30daysbeforeyourlicenseexpires,theIntegrationServersendsane mailmessagetotheadministrativemessagerecipient,remindinghimorhertorenewthe license.Inaddition,theserverdisplaysthefollowingmessageatthetopofallpageson theIntegrationServerAdministrator:
License key expires in about days days contact webMethods for a new key.
Renewing a Key
Ifyouneedtoobtainanewkeyorrenewyourlicense,contactyourSoftware AGsales representative.
Licensed Sessions
YourlicenseallowsaspecifiednumberofuserstohavesessionsintheIntegrationServer concurrently.TheIntegrationServercreatesasessionwhenadeveloperconnectstothe serverfromthewebMethodsDeveloperoraISclientconnectstotheservertoexecute services.Ifauserattemptstoaccesstheserverwhilethemaximumnumberofsessions areinuse,theserverrejectstherequestandreturnsthefollowingerrortotheuser:
Server has reached client limit.
Youcanviewthecurrentnumberofactivesessionsandthelicensedsessionlimitusing theStatisticsscreenintheIntegrationServerAdministrator.Thisvalueispermanently associatedwithyourlicensekeyandcanonlybechangedbyobtaininganewlicense. AnyconnectionmadetotheserverbyanonAdministratoruser(thatis,auserthatisnot partoftheAdministratorsgroup)consumesalicensedsession.Thesessionexistsuntilit timesout(basedontheserversSessionTimeoutsetting)ortherequesterstopsthe sessionbyinvokingthewm.server:disconnectservice. Ifauserinvokesastatelessserviceandasessiondoesnotalreadyexistfortheuser,the servercreatesasession.IftheuserisanonAdministrator,theuserconsumesalicensed session.Aftertheservicecompletes,theserverremovesthesessionandreducesthe numberoflicensedsessionsinuse. To view the current number of active sessions and the licensed sessions limit 1 2 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheServermenuoftheNavigationpanel,clickStatistics. TheserverdisplaysthecurrentnumberofactivesessionsinuseintheTotal Sessions field.Theserverdisplaysthemaximumnumberoflicensedsessionsyourlicense allowsintheLicensed Sessions fields. Fordetailedinformationabouttheactivesessions,clickthenumberintheTotal Sessions field.
63
Managing the Server Thread Pool

Tobettertuneyourserversperformance,youcanconfiguretheminimumandmaximum numberofthreads.Theserverusesthreadstoexecuteservices,retrievedocumentsfrom theBroker,andexecutetriggers.Whentheserverstarts,thethreadpoolinitiallycontains theminimumnumberofthreads.Theserveraddsthreadstothepoolasneededuntilit reachesthemaximumallowed.Ifthismaximumnumberisreached,theserverwaitsuntil processescompleteandreturnthreadstothepoolbeforebeginningmoreprocesses. Youcanalsosetawarninglevelforavailablethreads.Whenthepercentageofavailable threadsisequaltoorlessthanthewarninglevel,theservergeneratesajournallog messagetoalertyoutothereducedthreadavailability.Theservergeneratesanother journallogmessagewhenthenumberofavailablethreadsisgreaterthanthethreshold. To configure the server thread pool 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickResources. ClickEdit Resource Settings. UnderServer Thread Pool,updatetheserverthreadpoolsettings,asfollows: For this parameter Maximum Threads Specify Themaximumnumberofthreadsthattheservermaintainsin theserverthreadpool.Ifthismaximumnumberisreached, theserverwaitsuntilprocessescompleteandreturnthreads tothepoolbeforerunningmoreprocesses.Thedefaultis75. Theminimumnumberofthreadstheservermaintainsinthe serverthreadpool.Whentheserverstarts,thethreadpool initiallycontainsthisminimumnumberofthreads.The serveraddsthreadstothepoolasneededuntilitreachesthe maximumallowed,whichisspecifiedintheMaximum Threads field.Thedefaultis10. Thresholdatwhichtheserverstartstowarnofinsufficient availablethreads.Whenthepercentageofavailableserver threadsequalsthispercentage,theservergeneratesaJournal logmessageindicatingthecurrentavailablethread percentageandstating:
Available Thread Warning Threshold Exceeded
Minimum Threads
Available Threads Warning Threshold
Thedefaultis15%.
64
For this parameter
Specify Whenyouenterapercentageandsaveyourchanges,the serverautomaticallycalculatesthenumberofthreadsand displaysthenumbernexttothespecifiedpercentage. Tip! Whenthepercentageofavailablethreadsfallsbelowthe warninglevel,youmightwanttodecreasethenumberof documentstheserverreceivesandprocessesforBroker/local triggers.Formoreinformation,seeChapter 23,Managing Broker/LocalTriggers.
Scheduler Thread Throttle
Percentageofserverthreadstheschedulerfunctionis permittedtouse. Thedefaultis75%.
ClickSave Changes.
Setting the Session Timeout Limit

WhenaremoteclientconnectstotheIntegrationServer,theserverstartsasessionfor thatclient.Thatsessionremainsactiveuntiltheclientapplicationspecificallyissuesa disconnectinstructiontotheserver(whichforcesanimmediatetermination)orthe sessiontimesoutduetoinactivity,whichevercomesfirst. Ifasessionisidle(inactive)foralongperiodoftime,itusuallymeansthattheclientisno longeractiveorthattheconnectionbetweenclientandtheserverhasbeenlost.The serverconstantlymonitorsforinactivesessions,andterminatessessionsthatareidlefor morethantheallowedperiodoftime.Iftheserverdidnottakestepstoclearoutsuch sessions,theywouldremainactiveindefinitely,wastingvaluableserverresources. YouusetheSession Timeout parametertospecifythelengthoftimeyouwillallowanidle sessiontoremainactive(inotherwords,howlongyouwanttheservertowaitbefore terminatinganidlesession).TosettheSession Timeoutparameterappropriately,youmust befamiliarwiththeclientsthatuseyourserver. IfyourclientsareallJavaprograms,youcanusuallyreducethetimeoutvalueto6or7 minutes.Youmayneedtoexperimentwiththissettingtofindtheappropriatevaluefor yoursite.Bydefault,theserverusesatimeoutlimitof10minutes.Thisisanappropriate valueformostsites.However,youmayhavetoincreasethisvalueifyourclients normallyhavelengthydelays(greaterthan10minutes)betweensuccessiverequests.
65
To set the session timeout limit 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickResources. ClickEdit Resource Settings. IntheSession Timeoutfield,typethenumberofminutesyouwanttheservertowait beforeterminatinganidlesession. ClickSave Changes.
Configuring Outbound HTTP Settings

OutboundHTTPparameterscontrolhowtheserverpresentsandprocessesoutbound HTTPandHTTPSrequests(i.e.,requeststhattheIntegrationServerissuesonbehalfofa client).Theparameterscontrolbehaviorsuchashowlongtheserverwaitsforaresponse, howmanytimesitretriesafailedrequest,andsoforth. DeveloperscanoverridesomeoftheserversoutboundHTTPsettingdefaultsatrun time,asisdescribedbelow. User Agent TheUser AgentparameterspecifiesthevaluethattheserverusesintheHTTPUserAgent requestheaderthatitsendswhenrequestingaWebdocument.TheUserAgentheader tellsaWebserverwhattypeofbrowserismakingtherequest.Inthecaseofthe IntegrationServer,theUserAgentheaderindicatesthetypeofbrowserthatthe IntegrationServerappearstobetotheWebserver.SomeWebserversexaminethis headertodetermineaclientscapabilitiessotheycantailortheirresponsesaccordingly. WhenyouinstalltheIntegrationServer,theUser AgentparameterissettoMozilla/4.0[en] (WinNT;I).Youcanchangethisvalueasyouneed;however,thevalueyousetshould satisfythemajorityofservicesthatyourserverexecutes. BesureyourdevelopersknowtheUser Agentvalueyourserveruses.Iftheirapplications requireadifferentUser Agent,theycanoverridetheserversdefaultatruntimeby includinganHTTPUserAgentheaderwiththeirrequest. Maximum Redirects TheMaximum RedirectsparameterspecifiesthenumberoftimesthattheIntegrationServer allowsarequesttoberedirected(i.e.,automaticallysenttoanotherURLbythetarget server.Ifarequestexceedsthespecifiednumberofredirections,theIntegrationServer immediatelyreturnsanI/Oexceptiontotheclient. WhenyouinstalltheIntegrationServer,Maximum Redirectsissetto5.Youwillneedto increasethisvalueifthetargetsthatyouaccesstypicallyredirecttheirrequestsmorethan this.(Thismayhappenifthetargetoperatesinaclusteredenvironment.)
66
Timeout TheTimeoutparameterspecifiesthelengthoftimetheserverwaitsforaresponsefroma targetserver.IftheIntegrationServerdoesnotreceivearesponseintheallottedtime,it retriestherequestuptothenumberoftimesspecifiedbytheRetriesparameter.Whenthe allowednumberofretriesisexceeded,theserverreturnsanexception. WhenyouinstalltheIntegrationServer,theTimeoutparameterissetto3minutes.For mostsitesthisisareasonablesetting;however,youmayneedtoadjustthisvalueifyou workwithtargetsthathavelongerresponsetimesthanthis(e.g.,largecommercialWeb sitesordatabasesduringpeakperiods). Retries TheRetriesparameterspecifiesthenumberoftimestheserverreissuesarequestthathas timedout(i.e.,onefromwhichitdidnotreceivearesponsewithinthetimeperiod specifiedbytheTimeoutparameter). WhenyouinstalltheIntegrationServer,Retriesissetto0.Thismeansthattheserver automaticallyreturnsanexceptionifitdoesnotgetaresponsewithintheallottedtime. SetRetriestoavaluegreaterthan0ifyouwanttheservertoretry(reissue)timedout requests.Theserverwillretrytherequestthenumberoftimesyouspecify. MakesurethatyourdevelopersknowtheRetriesvaluethatyourserveruses.Iftheyneed touseadifferentvalue,theycanexplicitlyassignaRetriesvaluetotheirservice.
Specifying Outbound HTTP Settings

UsethefollowingproceduretospecifytheOutboundHTTPSettings. To set the Outbound HTTP Settings 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickResources. ClickEdit Resource Settings. SettheOutbound HTTP Settings asfollows: For this parameter User Agent Specify ThestringthatyouwanttheservertosupplyintheHTTP UserAgentheaderiftheclientdoesnotspecifyavalue.Type thestringexactlyasyouwantittoappearintheHTTP header,includingspaces,symbols,andpunctuation. Anintegerthatindicatesthenumberoftimestoallowa requesttoberedirectedbeforetheserverreturnsanI/O exceptiontotheclient.
Maximum Redirects
67
For this parameter Timeout
Specify Anintegerthatindicatesthenumberofsecondstheserver waitsforaresponsefromthetargetserverbeforeretrying theserviceorreturningatimeouterrortotheclient. Anintegerthatindicatesthenumberoftimestheserver retriesaservicethathastimedoutbeforereturningan exceptiontotheclient.
Retries
ClickSave Changes.
Setting Up Aliases for Remote Integration Servers

Youcansetupaliasesforremoteservers.Communicationthroughthealiasisoptimized, makingtransactionswiththeremoteserverfaster.Inaddition,usinganaliasismore convenientbecauseitsavesyoufromspecifyingconnectioninformationeachtimeyou communicatewiththeremoteserver. Usearemotealiaswhen: Invoking services on other Integration Servers.Afteryouestablishaliases,youcanusethe pub.remote:invoke andpub.remote.gd:* servicestoinvokeservicesonremoteserversby identifyingtheremoteserversbytheiraliases. Presenting multiple client certificates. TheIntegrationServercanpresentasingleclient certificatetoallserversoritcanpresentdifferentclientcertificatestodifferentSSL servers.Inaddition,theIntegrationServercanpresentcertificatesprovidedforthis purposebyotherorganizations.SettingupremotealiasesfortheseSSLserversmakes iteasiertopresentdifferentcertificatestothem.SeePresentingMultipleClient Certificatesonpage 148formoreinformation. Performing package replication.Forasubscribertosetupasubscriptionwithapublisher orpullapackagefromthepublisher,youmustdefinethepublishingserverasa remoteservertothesubscriber.Thealiastellsthesubscribingserverhowtoconnect tothepublishingservertosetupthesubscriptionorpullthepackage.SeeThe SubscribingServeronpage 308formoreinformation. Thedefinitionforanaliascontainstheconnectioninformationtheserverrequiresto connecttoaremoteserver.ItidentifiesthehostnameorIPaddressoftheremoteserver andindicateswhethertheservershoulduseanHTTPorHTTPSconnectiontoconnectto theremoteserver. Thealiasalsoidentifiesausernameandpasswordthattheserversuppliestotheremote server.Theremoteserverusestheusernameandpasswordtoauthenticatetheclientand todetermineiftheclientisauthorizedtoexecutetherequestedservice. Ineffect,thealiasgrantsaccesstoaremoteservicebyallowingtheusertoimpersonate anauthorizeduserontheremoteserver.Therefore,topreventunauthorizedusersfrom accessingservicesonremoteservers,thealiasalsocontainsaccesscontrolinformation.
68
YouspecifyanACLthatprotectstheuseofthealias.Ifaclientthatisauthorizedtouse thealiasmakesarequest,theserverwillrequesttheserviceontheremoteserver.Ifa clientthatisnotauthorizedtousethealiasmakesarequest,theserverrejectstherequest anddoesnotinvoketheserviceontheremoteserver.
Adding an Alias
UsethefollowingproceduretoaddanaliasforaremoteIntegrationServer. To add an alias for a remote server 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickRemote Servers. ClickCreate Remote Server Alias. SettheRemote Server Alias Propertiesasfollows: For this parameter Alias Specify Namethatyouwanttouseforthealias.Youcangivethe remoteserveranyaliasnamebutitcannotincludethe followingillegalcharacters: #&@^!%*:$./\\`;,~+=)(|}{][><. HostnameorIPaddressoftheremoteserverforwhichyouare creatinganalias(e.g.,workstation5.webmethods.com). Portnumberonwhichtheremoteserverlistensforincoming requestsfromyourserver(e.g.,5555). Usernameforauseraccountontheremoteserver.Whenyou invokeaserviceusingthisalias,theremoteserverusesthis useraccountforauthenticationandaccesscontrol.Specifya usernamethathasaccesstotheservicesyouwanttoinvokeon theremoteserver. Passwordidentifiedintheuseraccountfor User Name. ACLthatgovernswhichusergroupsonyourservercanuse thisaliasfortheremoteserver.SelectanACLfromthedrop downlist.Bydefault,onlymembersofgroupsgovernedbythe InternalACLcanusethisalias.
Host Name or IP Address Port Number User Name
Password Execute ACL
69
For this parameter Idle Timeout (in minutes) 0=none
Specify Numberofminutesthattheservermaintainsanidle connectiontotheremoteserver. Ifyouspecify0,thereisnotimeoutlimit;theservermaintains theconnectionuntilyourlocalserverisshutdownorthe sessionsthatareusingthealiasexpire.Anyremoteinvoke connectionthatisGLOBAL(insteadofSESSION)willsurvive indefinitely;therefore,useof0foratimeoutlimitisnot recommended.
Use SSL
Whetheryouwantyourservertoconnecttotheremoteserver usingSecureSocketsLayer(SSL).IfyouwanttouseSSL,select yes;otherwise,selectno. Important! Ifyouselectyes,theremoteservermustbe configuredtolistenforincomingHTTPSrequests.
Private Key Certificates
Specifiesthenameofthefilecontainingtheprivatekey associatedwiththisserversdigitalcertificate. Certificateyouwanttopresenttothisremoteserver.Youmust specifytheentirecertificatechainusingthisformat.Subject, Intermediate1 ,Intermediate2,,Root SubjectisthelocalIntegrationServerscertificate,thatis, thecertificateyouwanttopresenttotheremoteserver. Intermediate1andIntermediate2areoptionalintermediate certificatesinthecertificatechain. RootistherootCAcertificateofthecertificatechain. Specifythepathandfilenameforeachelementofthechain. Forexample:
config\cert.der,config\intermedcert.der,config/cacert.der
Retry Server
HostnameorIPaddress(e.g.,workstation6.webmethods.com) ofaremoteserveryouwantyourlocalIntegrationServerto connecttoiftheprimaryremoteserverisunavailable.Specify thisparameterifyouareusingtheremote:invokeand pub.remote.gd:*servicestoinvokeservicesonaremoteserverthat ispartofacluster.
ClickSave Changes.
70
Testing the Connection to a Remote Server

Afteryouaddanalias,youcantesttheconnectiontotheremoteservertoensurethatthe hostname(orIPaddress)andportnumberspecifiedforthealiasidentifiesanIntegration Serverthatiscurrentlyrunning.Usethefollowingproceduretotesttheconnection. To test the connection to a remote server 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickRemote Servers. Clickthe iconintheTestcolumnforthealiasyouwanttotest.
Theserverdisplaysastatuslinethatindicateswhethertheconnectionissuccessfulor not.Thestatuslineisdisplayedabovethelistofexistingaliases.
Editing an Alias
Ifyouneedtoupdatetheinformationforanalias,youcaneditittomakeyourchanges. Usethefollowingproceduretoeditanalias. To edit an alias for a remote server 1 2 3 4 5 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickRemote Servers. Locatethealiasyouwanttoeditandclickonthealiasname. Updatetheinformationforthealias. ClickSave Changes.
Deleting an Alias
Ifyounolongerneedanaliasforaremoteserver,youcandeleteit.Usethefollowing proceduretodeleteanalias. To delete an alias for a remote server 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickRemote Servers. Locatethealiasyouwanttodeleteandclickthe iconintheDeletefield.Theserver displaysadialogboxthatpromptsyoutoverifyyouraction.ClickOKtoverifythat youwanttodeletethealias.
71
Setting Up Aliases for Web Services

Thisisalsoknownasdynamicendpointaddressing.Theendpointaliasrepresentsthe networkaddressand,optionally,anysecuritycredentialstobeusedwithWebservices. ForaconsumerWebservicedescriptoranditsassociatedWebserviceconnectors,the aliasinformation(includingtheaddressinginformationandanysecuritycredentials),is usedatruntimetogeneratearequestandinvokeanoperationoftheWebservice. ForaProviderWSD,theendpointaddressisusedtoconstructthelocation=attributeof thesoap:addresselementwithinthewsdl:portelementwhenWSDLisrequestedforthe Webservice.ThesecuritycredentialsmaybeusedwhenconstructingaresponsetoaWeb servicerequest. Anendpointaliasisusuallycreatedforoneormoreofthefollowingreasons: Security.AnendpointaliasisrequiredinordertoconfigureWSSecurityforWeb serviceprovidersandconsumers. Efficiency.Usinganendpointaliassavesyoufromhavingtospecifyorchangethe serverinformationeachtimeyouusetheWebservice,sincetheactualvalueofthe endpointislookedupatruntime. WhenyoucreateaproviderWebservicedescriptor,youcanspecifyanexistingendpoint aliaswhichwillbedisplayed(andcanbechanged)fromtheWebservicedescriptors defaultbinder.Developerusesabindertocollectthedefinitionsforaddresses, communicationprotocols,anddataformatsforaparticularporttypeinonecontainer. YoucancreatemorebindersintheBinderstab,eachwithdifferentdefinitionsand endpointaliases.EachbinderprovidesanotheroptionforcommunicationbytheWeb service.Thedefaultbinder(s)foraconsumerWebservicedescriptorarecreatedfromthe WSDLonwhichitisbased. ThedefinitionforanendpointaliasidentifiesthehostnameorIPaddressoftheserver. ThealiasalsoidentifiesanoptionalusernameandpasswordthattheWebservice descriptorcanusewhencommunicatingwiththeserver. ForinformationaboutimplementingIntegrationServersWSSecurityfacility,including keyandcertificateusage,seetheWSSecuritychaptersinWebServicesDevelopersGuide.
Adding an Endpoint Alias

UsethefollowingproceduretoaddaWebserviceendpointaliastoIntegrationServer. To add an endpoint alias 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickWeb Services. ClickCreate Web Service Endpoint Alias.
72
4 5
UnderWeb Service Endpoint Alias PropertiesentertheAliasname.Thealiasnamecannot includethefollowingillegalcharacters:#&@^!%*:$./\\`;,~+=)(|}{][>< UnderHTTP Transport Properties,entertheIntegrationServerHost Name or IP Address andPort Number,asfollows: For this parameter Host Name or IP Address Port Number Specify HostnameorIPaddressoftheserverforwhichyouare creatinganalias(e.g.,workstation5.webmethods.com). AnactiveHTTPorHTTPStypeListenerport,definedonthe IntegrationServerspecifiedbytheHost Name or IP Address.
IfyouarenotconfiguringtheWebserviceendpointforsecurity,thenleavethe remainingsettingsunderHTTP Transport PropertiesandWS-Security Propertiesblankand clickSave Changes. IfyouareconfiguringtheWebserviceendpointtouseanyofthesecurityoptions listedbelow,firstreadtheWSSecuritychapterintheWebServicesDevelopersGuide. TheWebServicesDevelopersGuideincludesdescriptionsoftheremainingfields,the TransportandMessagelevelparameters,andotherimportantsecurityinformation. YoucanclickSave ChangesnowandedittheHTTP Transport PropertiesandWS-Security Propertieslater. Thesesecurityoptionsinclude: UsingWSSecuritywithtransportbasedauthentication,suchasHTTPS. AWebservicethatusesasecuritypolicythat: RequiresthatSOAPmessagerequestsincludeaUsernameToken. RequiresthatSOAPmessageresponsesbedecrypted RequiresSOAPmessagerequestsbesigned. RequiresX.509authentication.
OnceyoucreateanendpointaliasforaWebservicedescriptor,youmustassociateit withbinder(seebelow).
73
Associate an Endpoint Alias with a Binder

OnceyoucreateaWebserviceendpointalias,youcanassociateitoneofthebindersina providerorconsumerWebservicedescriptor. To associate an endpoint alias with a Web service descriptor 1 2 3 4 5 6 StartDeveloper. OpenandlocktheWebservicedescriptortowhichyouwanttoassociatetheWeb serviceendpointalias. DoubleclicktheWebservicedescriptorandclicktheBinderstab. Clicktoselecttheappropriatebinder. InthePropertiespanel,locatethePort aliasproperty.SelecttheWebserviceendpoint aliasthatyouwanttoassociatewiththeWebservicedescriptorfromthelist. Savethechanges. Note: WhenthePort aliaspropertyismodifiedforaconsumerWebservice descriptorand,theWebservicedescriptorisviewedasWSDL(byclickingthe View WSDLbutton),thedisplayedWSDLdoesnotreflectthechangetotheport alias.TheoriginalWSDLusedtocreatetheWebservicedescriptorisdisplayed. However,thenewvaluewillbeusedatruntime.
Editing an Endpoint Alias

Ifyouneedtoupdatetheinformationforanendpointalias,youcaneditittomakeyour changes.Usethefollowingproceduretoeditanalias. To edit an endpoint alias: 1 2 3 4 5 6 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickWeb Services. Locatethealiasyouwanttoeditandclickonthealiasname. ClickEdit Web Service Endpoint Alias. Updatetheinformationforthealias. ClickSave Changes.
74
Deleting an Endpoint Alias

Ifyounolongerneedanendpointalias,youcandeleteit.Usethefollowingprocedureto deleteanalias. To delete an endpoint alias 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickWeb Services. Locatethealiasyouwanttodeleteandclickthe iconintheDeletefield.Theserver displaysadialogboxthatpromptsyoutoverifyyouraction.ClickOKtoverifythat youwanttodeletethealias. Note: Thedefaultaliascannotbedeleted,sothe disabled. iconintheDeletefieldis
Specifying a Third-Party Proxy Server for Outbound Requests

WhentheIntegrationServerexecutesarequestagainstaremoteserver(forexamplea remoteinvokeagainstanotherIntegrationServer),oraLoadDocumentservice,itissues anHTTP,HTTPS,orFTPrequesttothespecifiedtargetserver.IfyourIntegrationServer sitsbehindafirewallandmustroutetheserequeststhroughathirdpartyproxyserver, youmustdefinetheaddressoftheproxyserverusingtheIntegrationServer Administrator. IfyouwanttoisolateyourIntegrationServerbehindaninternalfirewall,youcan providegreatersecuritybyrunningaspecialReverseHTTPGatewayServerinyour DMZanddisallowingallinboundconnectionstoyourinternalserver.Forinformation aboutsettingupaReverseHTTPGatewayServer,seeChapter 15,SettingUpaReverse HTTPGatewayonpage 219. TheIntegrationServerallowsyoutodefinethreeproxies:onetouseforoutboundHTTP requests,onetouseforoutboundHTTPSrequests,andonetouseforoutboundFTP requests. To specify a Proxy Server 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickProxy Servers. ClickEdit Proxy Settings.
75
SettheProxy (HTTP)andSecure Proxy (HTTPS)andFTP Proxy (FTP)parametersasfollows. (Ifyouuseaproxyserverforonlyonerequesttype,completetheparametersforthat type,andleavetheparametersfortheothertypesempty.) For this parameter Proxy Host Proxy Port Proxy User Proxy Pass Proxy Type (forFTPonly) Specify Thenameoftheproxyserver. TheportonwhichtheproxyserverlistensforHTTP,HTTPS, and/orFTPrequests. TheusernametheIntegrationServermustusewhen accessingthisproxyserver(ifoneisrequired). ThepasswordtheIntegrationServermustusetoaccessthis proxyserver(ifoneisrequired). TypeofFTPproxyservertoconnecttousingthepub:client.ftp builtinservice.TheproxyserveralwaysrequirestheFTP servername,FTPusername,andtheFTPuserpassword.The methodyouusetosendthisinformationtotheFTPproxy serverdependsonthetypeofproxyserveryouhave.The IntegrationServersupportsthefollowingproxyservertypes: 0. No proxy DonotuseanFTPproxyserver.Thisisthedefault. 1. user@host no proxy auth. Connecttotheproxyserver,butdonotlogintoit. Thensendthefollowing: USER ftp_user@real_ftp_hostname
PASS ftp_password
2. user@host proxy auth Connecttotheproxyserver,andlogintoitwith: USER proxy_user

PASS proxy_password
Thensendthefollowing: USER ftp_user@real_hostname

PASS ftp_password
3. site command Connecttotheproxyserverandlogintoitwith: USER proxy_user

PASS proxy_password
Thensendthefollowing: SITE real_ftp_hostname

USER ftp_user PASS ftp_password
76
For this parameter
Specify 4. open command Connecttotheproxyserverandlogintowith: USER proxy_user

PASS proxy_password
Thensendthefollowing: OPEN real_ftp_hostname

USER ftp_user PASS ftp _password
5. real_user@proxy_user@real_host Connecttotheproxyserverandlogintoit,thensendthe following:

USER ftp_user@proxy_user@real_hostname PASS ftp_password@proxy_password
ClickSave Changes.
Bypassing a Proxy Server

IfyouareusingaproxyserverforoutboundHTTP,HTTPS,and/orFTP,youcan optionallyrouteselectedrequestsdirectlytotheirtargets,bypassingtheproxy. Todothis,youusetheIntegrationServerAdministratortodefinethelistofdomainsto whichyouwanttheIntegrationServertoissuerequestsdirectly. To bypass a proxy server 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickProxy Servers. ClickEdit Proxy Settings. IntheProxy Bypass field,typethefullyqualifiedhostanddomainnameofeachserver towhichyouwanttheIntegrationServertoissuerequestsdirectly.Typethehost nameandthedomainnameexactlyasitwillappearintheURLsthattheserveruses. Toentermultiplenames,separateeachwithcommas. Youcanusetheasterisk(*)toidentifyseveralserverswithsimilarnames.Theasterisk matchesanynumberofcharacters.Forexample,ifyouwantedtobypassrequests madetolocalhost,www.yahoo.com,home.microsoft.com,andallhostswhosenames beginwithNYC,youwouldtype:
localhost,www.yahoo.com,home.microsoft.com, NYC*.*
ClickSave Changes.
77
Configuring Where the Integration Server Writes Logging, Status, and Other Information
TheIntegrationServercollectsandstoresinformationaboutthefollowingareas: Central User Management: InformationaboutuserswhoneedaccesstoIntegration ServerorwebMethodsTradingNetworksthroughMywebMethodsinterfaces. Document History:HistoryofdocumentsreceivedbytriggersontheIntegrationServer. Theserverusesthisinformationduringduplicatedetectiontodeterminewhethera triggeralreadyreceivedandprocessedadocument.Formoreinformationabout usingdocumenthistorydata,seethePublishSubscribeDevelopersGuide.For informationaboutconfiguringadocumenthistorydatabase,seewebMethods InstallationGuide. Internal Server Functions: InformationaboutvariousIntegrationServerfunctionssuch asscheduledjobs,guaranteeddelivery,andtriggerjoins.Formoreinformationabout storingthisinformation,seethewebMethodsInstallationGuide. Key Cross Referencing and Echo Suppression:Crossreferencekeysandprocessintegrity statusinformation.Thisinformationisrequiredtosynchronizeupdatesamong variousapplicationsandthedatabasestheyreference.Formoreinformationabout storingcrossreferencedata,seethePublishSubscribeDevelopersGuide. Logging:Auditinginformationaboutserviceexecution(audit,error,session, guaranteeddelivery,andsecurity)ontheIntegrationServer.Alsoincludesauditing informationaboutprocesses.TheseincludeprocessesgeneratedbyBusinessProcess Modeler.ThewebMethodsMonitorusesthisinformationtoresubmitfailed processesandservices.Formoreinformationaboutstoringloggingdata,seethe webMethodsLoggingGuide. Note: Youcanenableordisableloggingusingserverconfigurationparameters, anddisableorenableuseofatemporaryloggingstore.Formoreinformation,see thedescriptionsofthewatt.server.auditLog,watt.server.auditLog.error, watt.server.auditLog.gd,watt.server.auditLog.security, watt.server.auditLog.session,andwatt.server.auditSyncserverconfiguration parametersinAppendix B,ServerConfigurationParameters. Trading Networks: DatabaseusedbyTradingNetworks.Formoreinformationabout storingTradingNetworksdata,seethewebMethodsInstallationGuide. IntegrationServerconnectstodatabasesthatstoretheinformationmentionedaboveby usingfunctionalaliasesandJDBCconnectionpools. Note: IntegrationServerdoesnotusefunctionalaliasesandJDBCconnectionpoolsto connecttoWmDBortheJDBCAdapter.
78
Switching from the Embedded Database to an External RDBMS

IfyouinstalledyourIntegrationServerwithanembeddeddatabase,butnowwantto switchtoanexternalRDBMS,followthesesteps: 1 2 3 NavigatetotheSecurity > Certificates > Client Certificates screenontheIntegrationServer Administrator,andmakeanoteofthecertificatemappings. CreatetheISInternalandCrossReferencedatabasecomponentsandconnectthemto JDBCconnectionpools.SeethewebMethodsInstallationGuideforinstructions. Runthemigrationutilitypub.scheduler:migrateTasksToJDBCtomigrateyourscheduled tasksfromtheembeddeddatabasetotheexternalRDBMS.SeethewebMethods IntegrationServerBuiltInServicesReferenceformoreinstructions. Note: Thisservicemigratesscheduledtasksonly;certificatemappingsandrun timedatastoredintheembeddeddatabasewillnotbemigrated. 4 NavigatetotheSecurity > Certificates > Client CertificatesscreenontheIntegrationServer Administratorandrespecifyyourcertificatemappings.RefertoImportingaClient CertificateandMappingIttoaUseronpage 186forinstructions.
Working with Extended Configuration Settings

Theremaybetimeswhenyouwanttoviewspecialserverpropertysettings.These propertiesarespecifiedintheserver.cnffile,howeveryoucanviewthemandeditthem usingtheIntegrationServerAdministrator.Typically,youdonotneedtochangethese settingsunlessdirectedtobywebMethodsdocumentationorSoftware AGCustomer Care. Important! Typically,youwillusetheIntegrationServerAdministratortoset propertiesintheserver.cnffile,buttheremaybetimeswhenyouneedtoeditthefile directlywithatexteditor.Before updating this file directly, be sure to shut down the Integration Server.
To view and edit extended configuration settings 1 2 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickExtended. Theserverdisplaysascreenthatlistsconfigurationpropertiesspecifiedinthe server.cnffile. 3 Bydefault,nopropertiesareshown.Ifthepropertiesyouwanttoviewareshown, skipthisstep.Toselectpropertiestobedisplayed,clickShow and Hide Keys.
79
Theserverdisplaysalistofallpropertiesincludedintheserver.cnffile(theirvalues arenotshown.)Selecttheboxtotheleftofeachpropertyyouwanttheserverto displayandclickSave Changes.TheserverdisplaystheExtended Settingsscreenagain, thistimewiththeselectedpropertiesandtheirvaluesdisplayed. 4 Toadd,delete,orchangeapropertysetting,clickEdit Extended Settings andtypeyour changes. Important! Anychangeyoumakeherewillbereflectedintheserver.cnffile. 5 ClickSave Changes. Anypropertiesyouaddedwillautomaticallydisplayacheckmark intheShow and Hide Keyslistandwillbedisplayed,withtheirvalues,intheExtended Settingslist. 6 Restarttheserverforthechangestotakeeffect. a b c IntheupperrightcornerofanyIntegrationServerAdministratorscreen,click Shutdown and Restart. Selectwhetheryouwanttheservertowaitbeforerestartingortorestart immediately. ClickRestart.
Configuring Integration Server to Work with Servers Running HTTP 1.0 and Above
SometimeswhenyourIntegrationServerconnectstothepartnerserver,theservermay crashbeforesendingbackaresponse.IfyourIntegrationServermaintainsbackward compatibilitywithHTTP0.9,itdoesnotmandatearesponsecodeandconsequently,it treatsnoresponsefromthetargetserverasavalidresponse.Thisisanerror. IntegrationServernowcontainsawattpropertythatyoucansettoindicatewhetherit maintainscompatibilitywithanotherserverusingHTTP0.9. UsethefollowingproceduretoupdateyourIntegrationServertoworkwithservers runningHTTP1.0andaboveonly. To set Integration Server to work with servers running HTTP 1.0 and above 1 2 3 4 IntheSettingsmenuoftheNavigationpanel,clickExtended. ClickEdit Extended Settings Typewatt.server.http.pointnineSupport=false ClickSave Changes. Note: Setwatt.server.http.pointnineSupporttotrueifyouwantIntegrationServer tocommunicatewithserversusingHTTP0.9andabove.
80
Specifying Character Encoding

Toensureinterpretabilitywithotherapplications,theIntegrationServersupports multipleformsofcharacterencoding.Thefollowingtableshowsthedefaultsettingsand theserverpropertiesthatcontrolthem. Important! ConsultwithSoftware AGCustomerCarebeforechangingthesesettings. Thedefaultsettingsareappropriateinmostcases.Settingthemincorrectlycancause unpredictableresults. Thesepropertiesarespecifiedintheserver.cnffile,whichyoucanupdatebyusing theSettings > ExtendedscreenoftheIntegrationServerAdministrator.Forinstructions onusingthisscreen,seeWorkingwithExtendedConfigurationSettingson page 79. Action Reading and writing text files Reading text from and writing text to the network Default Setting YourJVMsfile.encoding property UTF8 Controlling Property
watt.server.fileEncoding
watt.server.netEncoding
Using a 64-bit JVM on Solaris and HP-UX Systems

Ifyouinstalleda64bitJVMona64bitAIXsystem,IntegrationServerwillusetheJVM automatically.Ifyouinstalleda64bitJVMona64bitSolarisorHPUXoperating system,youmustconfigureIntegrationServertousetheJVM. To configure Integration Server to use a 64-bit JVM 1 2 3 4 NavigatetotheIntegrationServer_directory/bindirectoryandopentheserver.shfilein atexteditor. Locatethe#JAVA_D64parameter. Uncommenttheparameterbydeletingthe#. Saveandclosethefile.
81
Publishing Information about Integration Server Assets

TheIntegrationServerAssetPublisherfeatureallowsyoutopublishinformationabout IntegrationServerpackagesorassetstoaMetadataLibrary.Usingthissharedlibrary, userscanaccessassetscreatedbyotherusers.Thiscapabilityisprovidedbythe WmAssetPublisherpackage.FormoreinformationaboutusingtheMetadataLibrary,see thewebMethodsMetadataLibraryUsersGuide.
82
Configuring Ports
84 85 85 88 93 98 101 103 107 109 114 115 115 117 117 118 118 119
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Considerations for Adding Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding an HTTP Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding an HTTPS Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding a File Polling Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding an FTPS Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding an FTP Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding an Email Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding an HTTP Diagnostic Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding an HTTPS Diagnostic Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Suspending an HTTP/HTTPS Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Resuming an HTTP/HTTPS Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying an FTP/FTPS Port Range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing the Primary Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting a Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing a Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling/Disabling a Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding a Security Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
83
7 Configuring Ports
Overview
TheIntegrationServerlistensforrequestsonportsthatyouspecify.Eachportis associatedwithaspecifictypeofprotocol:HTTP,HTTPS,FTP,FTPS,email,orfile polling.Inadditiontotheseporttypes,theIntegrationServeralsoprovidesadiagnostic portandsomespecialportsusedbytheReverseHTTPGatewayfacility.Formore informationabouttheReverseHTTPGateway,refertoChapter 15,SettingUpaReverse HTTPGateway. Thefollowingtabledescribestheporttypesthatyoucanconfigure
.
Use this port type... HTTP HTTPS Filepolling FTPS FTP Email Diagnostic
To... Submitunsecuredrequeststotheserver. SubmitrequeststotheserverusingSSL encryption. Monitorthefilesystemforthearrivalofnewfiles andperformspecialprocessinguponarrival. MovefilestoandfromtheserverusingSSL encryption. Movefilestoandfromtheserver. Receiverequeststhroughanemailserver,suchas POP3orIMAP. AccesstheIntegrationServerAdministratorwhen theserverbecomesunresponsive.
Refer to page... 85 88 93 103 101 103 107
Allportsareassociatedwithapackage.Bydefault,theyareassociatedwithWmRoot. Youcanassociateallporttypesexceptthediagnosticportwithanapplicationpackageso thatwhenyoureplicatethepackage,itcontinuestouseaportwiththesamenumberon thenewserver.Thisfeatureisusefulifyoucreateanapplicationthatexpectsinputona specificport.Theapplicationwillcontinuetoworkafteritisreplicatedtoanotherserver. Important! Becarefulwhensettingupaportthatisassociatedwithapackage.When copiedtothetargetserver,thenewportmightdecreasesecurityonthatsystem.For example,supposeyoureplicateapackagethatisassociatedwithanHTTPportat 5556.ThereplicationprocesscreatesanHTTPportat5556onthetargetserver.Ifthe targetservernormallyusesonlyHTTPSportsbecauseoftheirgreatersecurity,then thenewportpresentsapossiblesecurityholeonthatserver. Forsecurityreasons,bydefault,allportsexcept5555areconfiguredtodenyaccesstoall services,exceptservicesspecifiedinanallowlist.However,youcanconfigureindividual portstoallowaccesstomoreservicesasneeded.
84
7 Configuring Ports
Considerations for Adding Ports

Bydefault,theserverispreconfiguredwithHTTPanddiagnosticportsat5555and9999, respectively.Youcanconfigureoneormoreadditionalports.YoucanassociateanHTTP, HTTPS,FTP,FTPS,email,orfilepollingprotocolwiththeadditionalports.Youmight addadditionalports: Ifyouhaveapplicationsthatrequireaspecificportnumber. Ifyouwanttosupportmultipletypesoflisteningprotocols. Ifyouwanttoopenseveralportsforthesameprotocol. IfyouwanttodeployyourserverinaReverseHTTPGatewayconfiguration,in whichaReverseHTTPGatewayIntegrationServersitsinyourDMZandintercepts requestsbeforepassingthemtotheserverbehindyourinnerfirewall.For instructionsonaddingReverseHTTPGatewayPorts,seeChapter 15,SettingUpa ReverseHTTPGateway. Important! Forsecuritypurposes,whenyouaddanewport,theserverdefinestheport todenyaccesstoallservicesexceptthosespecifiedinanallowlist.Therefore,after addingaport,youmightneedtoperformadditionalstepstomakemoreservices availablethroughtheport.ThesestepsaredescribedinChapter 13,Authenticating Clients. Note: IfyourserverrunsonAS/400,limitthesizeoftheportqueuethatisavailableto theTCP/IPstack.Theportqueueisthenumberofoutstandinginboundconnections thatarequeuedintheTCP/IPstack.Addthefollowinglinetotheserverproperty settings: watt.server.portQueue=511 Forinstructionsabouthowtoaddserverpropertysettings,seeSwitchingfromthe EmbeddedDatabasetoanExternalRDBMSonpage 79.
Adding an HTTP Port

Bydefault,theIntegrationServerdefinesanHTTPportat5555.YoucanaddanHTTP portbycompletingtheinstructionsbelow. To add an HTTP port 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickPorts. ClickAdd Port. IntheAdd Portareaofthescreen,selectwebMethods/HTTP.
85
7 Configuring Ports
ClickSubmit.TheIntegrationServerdisplaysascreenrequestinginformationabout theport.Enterthefollowinginformation: For this parameter... Port Package name Specify Thenumberyouwanttousefortheport.Selectanumberthat isnotalreadyinuse. Thepackageassociatedwiththisport.Whenyouenablethe package,theserverenablestheport.Whenyoudisablethe package,theserverdisablestheport. Ifyoureplicatethispackage,theIntegrationServercreatesa portwiththisnumberandthesamesettingsonthetarget server.Ifaportwiththisnumberalreadyexistsonthetarget server,itssettingsremainintact.Thisfeatureisusefulifyou createanapplicationthatexpectsinputonaspecificport.The applicationwillcontinuetoworkafteritisreplicatedto anotherserver. Bind Address (optional) IPaddresstowhichtobindthisport.Specifyabindaddressif yourmachinehasmultipleIPaddressesandyouwantthe porttousethisspecificaddress.Ifyoudonotspecifyabind address,theserverpicksoneforyou. Howlongaconnectionrequestshouldstayinthequeuefora suspendedport,beforetherequestisrejected.Thedefaultis setto200milliseconds(ms),withamaximumpermissible valueof65535ms. Whentoclosetheconnectioniftheserverhasnotreceiveda requestfromtheclientwithinthistimeoutvalue(in milliseconds);orwhentoclosetheconnectioniftheclienthas explicitlyplacedacloserequestwiththeserver. Whetherthelistenerwillusethispoolexclusivelyfor dispatchingrequests.TheexistingIntegrationServerthread poolisaglobalthreadpool.Ifthereisaveryhighloadonthis resource,theusermayhavetowaitfortheglobalthreadpool toprocesshisrequest.However,withtheprivatethreadpool optionenabled,requestscomingintothisportwillnothaveto competewithotherserverfunctionsforthreads.
Backlog
Keep Alive Timeout
Threadpool
86
7 Configuring Ports
For this parameter...
Specify ClickEnableifyouwishtosetupaprivatethreadpoolfor requestscomingtothisport.Youcanchangeoracceptthe defaultsettingsgivenbelow: Threadpool Min 1 Referstotheminimumnumberofthreads. Thedefaultissetto1. Threadpool Max 5 Referstothemaximumnumberofthreadsfor thisprivatethreadpool.Thedefaultissetto5. Threadpool Priority 5 ThisistheJavathreadpriority. Important! Thissettingmustbeusedwithextremecarebecause itwillaffecttheserverperformanceandthroughput. ClickDisableifyoudonotneedtousetheThreadpoolfeature.
6 7 8
ClickSave Changes. OnthePortsscreen,clickEdittochangetheAccessModeifnecessary.YoumaySet Access Mode to Allow by DefaultorReset to default access settings. OnthePorts screen,alsocheckthelistofportstoensurethatthestatusintheEnabled columnisYes.Ifitisnot,clickNotoenabletheport.
Using Advanced Controls

Bydefault,theIntegrationServeracceptsportconnectionsrequestsassoonasitreceives them.Thiscanbeaproblemiftheportreceivesmultiplerequestssimultaneouslyand doesnothavetheresourcestohandlethem.Youcanhandlethisbyspecifyingadelay valueusingtheAdvancedControlsscreen.Withadelayvalueinplace,theIntegration Serverwillwaitthespecifiednumberofmillisecondsbeforeacceptingaconnection requestonthisport.TheAdvancedControlsscreenprovidesyouthecapabilitytocontrol therateatwhichthelisteneracceptsconnections,overthesizeoftheprivatethreadpool, ifitwasenable. To use advanced controls 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickPorts. YouwillseeaPort Listtableinthemainareaofthescreen. IntheAdvancedcolumnofthistable,clickEdit. TheIntegrationServerdisplaysascreenrequestinginformationaboutListenerand PrivateThreadPoolControls.NotethattheDiagnosticHTTPListenerStateand PrivateThreadpoolareasofthescreenarealreadypopulatedwithpredefinedvalues.
87
7 Configuring Ports
Enterthefollowinginformation: For this parameter... Listener Controls Specify Thetypeofcontrolsyouwanttoset,tomanagetherateat whichthelisteneracceptsconnectionsandothercontrols whentheprivatethreadpoolisenabled. Suspend.Stopsthelistenerfromacceptinganymore connectionsandsubsequentlydispatchinganymorerequests. Increase By.Increasesthetimethatthelistenerwillwaitbefore acceptingnewclientconnections. Decrease By.Decreasesthetimethatthelistenerwillwait beforeacceptingnewclientconnections. Set To(Delayms)Setsthedelaytimeintervalinmilliseconds. Private Thread Pool Controls Thetypeofthreadpoolcontrolyouwant,inordertoavoidthe needforyourporttocompetewithotherserverfunctions whentheIntegrationServerishandlingmultipleconnections. Increase By. Byhowmanythreadsyouwishtoincreasethe listenersthreadpool. Decrease By. Byhowmanythreadsyouwishtodecreasethe listenersthreadpool. Set To(Threads). Athowmanythreadsyouwishtosetyour threadpool.
ClickApplytoacceptyourchanges.Else,clickCancel.
Adding an HTTPS Port

TheHTTPSportenablestheIntegrationServertoauthenticatetheclientandserver securelyandencryptthedataexchanged.Bydefault,theHTTPSlistenerusesthe IntegrationServercertificate.However,youcanconfigurethelistenertouseitsown certificate,oraprivatekeyandcertificatechainresidinginakeystore(fileor SmartCard/HSMbased). Inaddition,youcanconfigurethetypeofclientauthenticationthatyouwanttheserver toperform.Clientauthenticationallowsyoutoverifytheidentityoftheclient. To add an HTTPS port 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickPorts. ClickAdd Port.
88
7 Configuring Ports
4 5 6
IntheAdd Portareaofthescreen,selectwebMethods/HTTPS. ClickSubmit.TheIntegrationServerdisplaysascreenrequestinginformationabout theport.Enterthefollowinginformation: ClickSave Changes. For this parameter... Port Package name Specify Thenumberyouwanttousefortheport.Selectanumberthat isnotalreadyinuse. Packageassociatedwiththisport.Whenyouenablethe package,theserverenablestheport.Whenyoudisablethe package,theserverdisablestheport. Ifyoureplicatethispackage,theIntegrationServercreatesa portwiththisnumberandthesamesettingsonthetarget server.Ifaportwiththisnumberalreadyexistsonthetarget server,itssettingsremainintact.Thisfeatureisusefulifyou createanapplicationthatexpectsinputonaspecificport.The applicationwillcontinuetoworkafteritisreplicatedto anotherserver. Bind Address (optional) IPaddresstowhichtobindthisport.Specifyabindaddressif yourmachinehasmultipleIPaddressesandyouwanttheport tousethisspecificaddress.Ifyoudonotspecifyabind address,theserverpicksoneforyou. Howlongaconnectionrequestshouldstayinthequeuefora suspendedport,beforetherequestisrejected.Thedefaultis setto200milliseconds(ms),withamaximumpermissible valueof65535ms. Whentoclosetheconnectioniftheserverhasnotreceiveda requestfromtheclientwithinthistimeoutvalue(in milliseconds);orwhentoclosetheconnectioniftheclienthas explicitlyplacedacloserequestwiththeserver. Whetherthelistenerwillusethispoolexclusivelyfor dispatchingrequests.TheexistingIntegrationServerthread poolisaglobalthreadpool.Ifthereisaveryhighloadonthis resource,theusermayhavetowaitfortheglobalthreadpool toprocesshisrequest.However,withtheprivatethreadpool optionenabled,requestscomingintothisportwillnothaveto competewithotherserverfunctionsforthreads.
Backlog
Keep Alive Timeout
Threadpool
89
7 Configuring Ports
Specify ClickEnableifyouwishtoenabletheprivatethreadpool settings.Youcanchangeoracceptthedefaultsettingsgiven below: Threadpool Min 1 Referstotheminimumnumberofthreads. Thedefaultissetto1. Threadpool Max 5 Referstothemaximumnumberofthreadsfor thisprivatethreadpool.Thedefaultissetto5. Threadpool Priority 5 ThisistheJavathreadpriority Important! Thissettingmustbeusedwithextremecarebecause itwillaffecttheserverperformanceandthroughput. ClickDisableifyoudonotneedtousetheThreadpoolfeature.
Client Authentication
ThetypeofclientauthenticationyouwanttheIntegration Servertoperform.SeeChapter 13,AuthenticatingClients formoreinformation. None. Theserverwillnotrequestclientcertificates.Iftheclient presentsacertificateanyway,theIntegrationServerprocesses it.Ifthecertificatematchesexactlyaclientcertificateonfileon theserver,theclientisloggedinastheuserpremappedtothe certificate.Otherwise,theserverpromptstheclientforauser IDandpassword. Request Client Certificates. Theserverwillrequestclient certificatesforallrequeststhatcomeinonthisHTTPSport.If theclientdoesnotprovideacertificate,therequestproceeds anyway.Ifthecertificatematchesexactlyaclientcertificateon file,theclientisloggedinastheusertowhichthecertificateis premapped.Otherwise,theserverpromptstheclientfora useridandpassword. Require Client Certificates. Theserverrequiresclientcertificates forallrequeststhatcomeinonthisHTTPSport.Forthe requesttosucceed,theclientmustpresentacertificatethat wassignedbyatrustedauthorityandthatmatchesexactlya clientcertificateonfileontheIntegrationServer.Ifthe certificatematchesaclientcertificateonfile,theclientis loggedinastheusertowhichthecertificatewaspremapped. Inallcases,ifthecertificatepresentedhasnotbeensignedbya trustedauthority,theIntegrationServerdoesnotuseit.
90
7 Configuring Ports
For this parameter... Servers Certificate
Specify Optional.Pathandfilenameofthefilethatcontainsthe IntegrationServersdigitalcertificate.Specifyavaluehere onlyifyouwantthisporttopresentadifferentserver certificatefromtheonespecifiedontheCertificatesscreen. Optional.Pathandfilenameofthefilethatcontainsthe certificateforthecertificateauthoritythatsignedthe IntegrationServersdigitalcertificate. Optional.Pathandfilenameofthefilethatcontainsthe privatekeyoftheprivate/publickeypairassociatedwiththe IntegrationServersdigitalcertificate.Ifyouleavethisfield blank,theIntegrationServerusestheprivatekeyspecifiedon theCertificatesscreen. Optional.Nameofthedirectory(relativetotheserverhome; orfullyqualifiedpath;ornetworkpaththatcontainsthe digitalcertificatesofcertificateauthoritiestrustedbythis server,forexampleconfig\cas.Ifyouleavethisfieldblank, theIntegrationServerusesthetrustedauthoritydirectory specifiedontheCertificatesscreen.Ifthetrustedauthorityfield isblankontheCertificatesscreenaswell,theserverthenchecks thevalueofthe
watt.security.cert.wmChainVerifier.trustByDefault
Authoritys Certificate Private Key
Trusted Authority Directory
property.IfthevalueisTrue (default),theservertrustsall certificates.IfthevalueisFalse,theservertrustsnocertificates. ---Or--KeyStore Location Optional.Thelocationondiskwherethekeystoreislocated (foranHSM/smartcardbackedkeystore,afileexistsondisk butdoesnotcontaintheactualprivatekey). Optional.Thepasswordwithwhichthekeystoreisprotected. IftheprivatekeyandcertificatechainarestoredonanHSM device,thispropertymustmatchthepasswordwithwhichthe cardwasprotected(forexample,fornCipherastheHSM provider,thispropertymustmatchtheOCS(OperatorCard Set)passwordforthecard).
KeyStore Password
91
7 Configuring Ports
For this parameter... KeyStore Type
Specify Optional.Thetypeofthekeystore.Differentvendorssupport differenttypesofkeystore;forexample,thedefaultSUN keystoreimplementationisoftypejks. Withinthisproperty,thenameinparenthesesisthenameof theSecurityProviderthatwillprovidesupportforthe keystoretype.Ifthedesiredproviderisnotlistedinthedrop downlist,youcanadditbyclickingtheAdd new Security Providerlink.Formoreinformationabouthowtoadda securityprovider,seeAddingaSecurityProvideron page 119. Aslongasaportwiththegivenproviderexists,youwillnot havetomanuallyreregisterthesecurityprovider.Ifthelast portwhichusesthisproviderisdeletedandtheIntegration Serverisrestarted,youmustreregisterthissecurityprovider beforeusingitforaport. Important! TheIntegrationServersupportsJKSandPKCS#12 keystoretypesonly.Otherkeystoretypesmayworkwith IntegrationServerbutarenotsupported.
HSM Based Keystore
Optional.Indicateswhetherornotthekeystoreisbackedby anHSMbasedkeystore(asmartcarddevicecanbeusedas well).Whenthekeystoreisbackedbysuchadevice,the privatekeydoesnotphysicallyleavetheHSMdeviceand certaincryptographicoperationsmustbeperformedonthat device. RequirediftheKeyStoreLocationparameterisdefined.Ifthe KeyStoreLocationparameterisnull,theAliaspropertyis ignored. Specifiesthealiasthatpointstotheprivatekeyandits associatedcertificatechaininthekeystore.Eachlistenerpoints toonealiasonthekeystore;therecanbemultiplealiasesinthe samekeystoreandmorethanonelistenercanusethesame alias.
Alias
Optional.Specifiesthenameofthedirectorythatcontainsthe certificatesofthecertificationauthorities(CAs)thatthisserver trustswhenitusesthisport;forexample, config\xApps\TrustedCAs. Note: Currentlythekeystorestoresonlytheprivatekeyandits associatedcertificatechain,notthetrustedCAcertificates.
92
7 Configuring Ports
7 8
OnthePortsscreen,clickEdittochangetheAccessModeifnecessary.YoumaySet Access Mode to Allow by DefaultorReset to default access settings. OnthePorts screen,alsocheckthelistofportstoensurethatthestatusintheEnabled columnisYes.Ifitisnot,clickNotoenabletheport.
Adding a File Polling Port

Afilepollingportperiodicallypollsamonitoringdirectoryforthearrivaloffilesand thenperformsspecialprocessingonthem.Whenitdetectsanewfile,theservercopies thefiletoaworkingdirectory,thenrunsaspecialfileprocessingserviceagainstthefile. Theservicemightparse,convert,andvalidatethefilethenwriteittothefilesystem.This service,whichyouwrite,istheonlyservicethatcanbeinvokedthroughthisport.You canlimitthefilestheserveracceptsbyfilteringforspecificfilenames. Forfilepollingtowork,youmustdothefollowing: 1 2 SetuptheMonitoringDirectoryontheIntegrationServer.Otherdirectoriesusedfor filepollingareautomaticallycreatedbytheIntegrationServer. WriteafileprocessingserviceandmakeitavailabletotheIntegrationServer.See XMLServicesDevelopersGuideandFlatFileSchemaDevelopersGuideforexamplesof suchservices. SetupthefilepollingportontheIntegrationServer.Directionsareprovidedbelow.
Whenyouconfigurethefilepollingport,youspecifyhowoftentopollforfiles,thename andlocationoftheprocessingservicetouse,filenamestofilterfor,aswellasother options. To add a file polling port 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickPorts. ClickAdd Port. IntheAdd Portareaofthescreen,selectwebMethods/FilePolling.
93
7 Configuring Ports
ClickSubmit.TheIntegrationServerdisplaysascreenrequestinginformationabout theport.Enterthefollowinginformation: For this parameter... Package Specify Package Name Packageassociatedwiththisport.Whenyouenablethe package,theserverenablestheport.Whenyoudisablethe package,theserverdisablestheport.Ifyouareperforming specialfilehandling,specifythepackagethatcontainsthe servicesthatperformthatprocessing.Ifyouwanttoprocess flatfilesfromthisport,selectWmFlatFile, whichcontainsbuilt inservicesyoucanusetoprocessflatfiles. Note: Ifyoureplicatethispackage,whethertoaserveronthe samemachineoraserveronaseparatemachine,afilepolling portwiththesamesettingsiscreatedonthetargetserver.Ifa filepollingportalreadyexistsonthetargetserver,itssettings remainintact.Iftheoriginalandtargetserversresideonthe samemachine,theywillsharethesamemonitoringdirectory. Ifthetargetserverresidesonanothermachine,bydefault, anothermonitoringdirectorywillbecreatedonthetarget serversmachine. Security Run services as user Usernameyouwanttousetoruntheservicesassignedtothe filepollingdirectory.Click tolookupandselectauser.The usercanbeaninternalorexternaluser. Polling Information Monitoring Directory DirectoryonIntegrationServerthatyouwanttomonitorfor files. Working Directory (optional) DirectoryontheIntegrationServertowhichtheserver shouldmovefilesforprocessingaftertheyhavebeen identifiedintheMonitoring Directory.Filesmustmeetageand filenamerequirementsbeforebeingmovedtotheWorking Directory.Thedefaultsubdirectory, MonitoringDirectory\..\Work,isautomaticallycreatedifno directoryisspecified.\ Completion Directory (optional) DirectoryonIntegrationServertowhichyouwantfiles movedwhenprocessingiscompletedintheMonitoring DirectoryorWorking Directory.Thedefaultsubdirectory, MonitoringDirectory\..\Done,isautomaticallycreatedifno directoryisspecified.
94
7 Configuring Ports
Specify Error Directory OptionalDirectoryonIntegrationServertowhichyouwant filesmovedwhenprocessingfails.Thedefaultsubdirectory, MonitoringDirectory\..\Error,isautomaticallycreatedifno directoryisspecified. File Name Filter (optional) ThefilenamefilterforfilesintheMonitoring Directory.The serveronlyprocessesfilesthatmeetthefilterrequirements.If youdonotspecifythisfield,allfileswillbepolled.Youcan specifypatternmatchinginthisfield. File Age (optional) Theminimumage(inseconds)atwhichafileintheMonitoring Directorycanbeprocessed.Theserverdeterminesfileage basedonwhenthefilewaslastmodifiedonthemonitoring directory.Youcanadjustthisageasneededtomakesurethe serverdoesnotprocessafilebeforetheentirefilehasbeen copiedtotheMonitoringDirectory.Thedefaultis0. Content Type Contenttypetouseforthefile.Theserverusesthecontent handlerassociatedwiththecontenttypespecifiedinthis field.Ifnovalueisspecified,theserverperformsMIME mappingbasedonthefileextension. Allow Recursive Polling WhethertheIntegrationServeristopollallsubdirectoriesin theMonitoring Directory. SelectYesorNo. Enable Clustering WhethertheIntegrationServershouldallowclusteringinthe MonitoringDirectory.SelectYesorNo. Lock File Extension Definesthepollingforaparticular extension.
95
7 Configuring Ports
For this parameter... Message Processing
Specify Processing Service NameoftheserviceyouwanttheIntegrationServerto executeforpolledfiles.Theserverexecutesthisservicewhen thefilehasbeencopiedtotheWorkingdirectory.Thisservice shouldbetheonlyserviceavailablefromthisport. Important! Ifyouchangetheprocessingserviceforafile pollingport,youmustalsochangethelistofservices availablefromthisporttocontainjustthenewservice.See belowformoreinformation. File Polling Interval Howoften(inseconds)youwantIntegrationServertopoll theMonitoring Directoryforfiles. Log Only When Directory Availability Changes IfyouselectNo(thedefault),thelistenerwilllogamessage everytimethemonitoringdirectoryisunavailable. IfyouselectYes,thelistenerwilllogamessageineitherofthe followingcases: Thedirectorywasavailableduringthelastpollingattempt butnotavailableduringthecurrentattempt Thedirectorywasnotavailableduringthelastpolling attemptbutisavailableduringthecurrentattempt Listening Directory is an NFS Mounted File System ForuseonaUNIXsystemwherethemonitoringdirectory, workingdirectory,completiondirectory,and/orerror directoryarenetworkdrivesmountedonthelocalfilesystem. IfyouselectNo(thedefault),thelistenerwillcalltheJava File.renameTo()methodtomovethefilesfromthemonitoring directorytotheworkingdirectory,andfromtheworking directorytothecompletionand/orerrordirectory. IfyouselectYes,thelistenerwillfirstcalltheJava File.renameTo()methodtomovethefilesfromthemonitoring directory.Ifthismethodfails,thelistenerwillthencopythe filesfromthemonitoringdirectorytotheworkingdirectory anddeletethefilesfromthemonitoringdirectory.This operationwillfailifeitherthecopyactionorthedeleteaction fails.Thesamebehaviorapplieswhenmovingfilesfromthe workingdirectorytothecompletionand/orerrordirectory.
96
7 Configuring Ports
Specify Cleanup Service OptionalThenameoftheservicethatyouwanttousetoclean upthedirectoriesspecifiedunderPolling Information. Cleanup At Startup WhethertocleanupfilesthatarelocatedintheCompletion DirectoryandError Directorywhenthefilepollingportis started. Cleanup File Age OptionalThenumberofdaystowaitbeforedeleting processedfilesfromyourdirectories.Thedefaultis7days. Cleanup Interval OptionalHowoften(inhours)youwantIntegrationServerto checktheprocessedfilesforcleanup.Thedefaultis24hours Maximum Number of Invocation Threads ThenumberofthreadsyouwanttheIntegrationServertouse forthisport.Typeanumberfrom110.Thedefaultis10.
6 7
ClickSave Changes. Makesuretheportsaccessmodeisproperlysetandthatthefileprocessingserviceis theonlyserviceaccessiblefromtheport. d e f g h i InthePortsscreen,clickEditintheAccess Modefieldfortheportyoujustcreated. ClickSet Access Mode to Deny by Default. ClickAdd Folders and Services to Allow List. TypethenameoftheprocessingserviceforthisportinthetextboxunderEnter one folder or service per line. Removeanyotherservicesfromtheallowlist. ClickSave Additions. Note: Ifyouchangetheprocessingserviceforafilepollingport,rememberto changetheAllowListfortheportaswell.Followtheproceduredescribedabove toaltertheallowedservicelist.
97
7 Configuring Ports
Adding an FTPS Port

TheFTPS(FTPoverSSL)portenablestheservertoauthenticatetheFTPclientandserver inasecuremanner,andencryptthecontrolanddataexchangebetweentheFTPclient andserver. Bydefault,theFTPSportwillworkonlywithsecureclients.Asecureclientisaclientthat securestheconnectionbyissuingtheAUTHcommand.YoualsocanconfiguretheFTPS listenertooperatewithclientsthatarenotsecure. YoucanconfiguretheFTPSporttouseitsowncertificateorusetheIntegrationServer certificate,ortorequestorrequireclientcertificates.Inaddition,youcanconfigurethe listenertouseaprivatekeyandcertificatechainresidinginakeystore(fileor SmartCard/HSMbased).Formoreinformationaboutclientcertificates,seeChapter 13, AuthenticatingClients. ToaddanFTPSport,completetheinstructionsbelow. To add an FTPS port 1 2 3 4 5 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickPorts. ClickAdd Port. IntheAdd Portareaofthescreen,selectwebMethods/FTPS. ClickSubmit.TheIntegrationServerdisplaysascreenrequestinginformationabout theport.Enterthefollowinginformation: For this parameter... Port Client Authentication Specify Thenumberyouwanttousefortheport.Selectanumber thatisnotalreadyinuse. ThetypeofclientauthenticationyouwanttheIntegration Servertoperform.SeeChapter 13,AuthenticatingClients formoreinformation. Note: FTPSclientsarealwayspromptedforauseridand password. None. Theclientlogsinastheuserspecifiedonthe userid/passwordprompt. Request Client Certificates. Theserverrequestsclient certificatesforallrequeststhatcomeinonthisFTPSport, butacertificateisnotrequiredforlogin.
98
7 Configuring Ports
Specify Require Client Certificates. Theserverrequiresclientcertificates forallrequeststhatcomeinonthisFTPSport.Ifno certificateisprovided,orifthecertificateisnottrusted,the IntegrationServerrejectstherequest. Bydefault,theIntegrationServerdoesnotperform certificatemappingforFTPSports.Tousethisfeature,you mustsetthewatt.net.ftpUseCertMapconfigurationproperty totrue.Formoreinformationabouthowclient authenticationworksforFTPSports,seeChapter 13, AuthenticatingClients.Formoreinformationabout certificatemapping,seeImportingaClientCertificateand MappingIttoaUseronpage 186.
Package name
Packageassociatedwiththisport.Whenyouenablethe package,theserverenablestheport.Whenyoudisablethe package,theserverdisablestheport. Ifyoureplicatethispackage,theIntegrationServercreatesa portwiththisnumberandthesamesettingsonthetarget server.Ifaportwiththisnumberalreadyexistsonthetarget server,itssettingsremainintact.Thisfeatureisusefulifyou createanapplicationthatexpectsinputonaspecificport. Theapplicationwillcontinuetoworkafteritisreplicatedto anotherserver.
Bind Address (optional)
IPaddresstowhichtobindthisport.Specifyabindaddress ifyourmachinehasmultipleIPaddressesandyouwantthe porttousethisspecificaddress.Ifyoudonotspecifyabind address,theserverpicksoneforyou. SelectthisoptiontopreventtheFTPSlistenerfromoperating withnonsecureclients. Optional.Pathandfilenameofthefilethatcontainsthe IntegrationServersdigitalcertificate.Specifyavaluehere onlyifyouwantthisporttopresentadifferentserver certificatefromtheonespecifiedontheCertificatesscreen. Optional.Pathandfilenameofthefilethatcontainsthe certificateforthecertificateauthoritythatsignedthe IntegrationServersdigitalcertificate. Optional.Pathandfilenameofthefilethatcontainsthe privatekeyoftheprivate/publickeypairassociatedwiththe IntegrationServersdigitalcertificate.Ifyouleavethisfield blank,theIntegrationServerusestheprivatekeyspecified ontheCertificatesscreen.
Secure Clients Only Servers Certificate
Authoritys Certificate
Private Key
99
7 Configuring Ports
For this parameter... Trusted Authority Directory
Specify Optional.Nameofthedirectory(relativetotheserverhome; orfullyqualifiedpath;ornetworkpaththatcontainsthe digitalcertificatesofcertificateauthoritiestrustedbythis server,forexampleconfig\cas.Ifyouleavethisfieldblank, theIntegrationServerusesthetrustedauthoritydirectory specifiedontheCertificatesscreen.Ifthetrustedauthority fieldisblankontheCertificatesscreenaswell,theserverthen checksthevalueofthe

property.IfthevalueisTrue (default),theservertrustsall certificates.IfthevalueisFalse,theservertrustsno certificates. ---Or--KeyStore Location Optional.Thelocationondiskwherethekeystoreislocated (foranHSM/smartcardbackedkeystore,afileexistsondisk butdoesnotcontaintheactualprivatekey). Optional.Thepasswordwithwhichthekeystoreis protected.Iftheprivatekeyandcertificatechainarestored onanHSMdevice,thispropertymustmatchthepassword withwhichthecardwasprotected(forexample,fornCipher astheHSMprovider,thispropertymustmatchtheOCS (OperatorCardSet)passwordforthecard). Optional.Thetypeofthekeystore.Differentvendors supportdifferenttypesofkeystore;forexample,thedefault SUNkeystoreimplementationisoftypejks(nCipheralso usesthistype). Withinthisproperty,thenameinparenthesesisthenameof theSecurityProviderthatwillprovidesupportforthe keystoretype.Ifthedesiredproviderisnotlistedinthe dropdownlist,youcanadditbyclickingtheAddnew SecurityProviderlink.Formoreinformationabouthowto addasecurityprovider,seeAddingaSecurityProvider onpage 119. Aslongasaportwiththegivenproviderexists,youwillnot havetomanuallyreregisterthesecurityprovider.Ifthelast portwhichusesthisproviderisdeletedandtheIntegration Serverisrestarted,youmustreregisterthissecurity providerbeforeusingitforaport. Important! TheIntegrationServersupportsJKSandPKCS#12 keystoretypesonly.Otherkeystoretypesmayworkwith IntegrationServerbutarenotsupported.
KeyStore Password
KeyStore Type
100
7 Configuring Ports
For this parameter... HSM Based Keystore
Specify Optional.Indicateswhetherornotthekeystoreisbackedby anHSMbasedkeystore(asmartcarddevicecanbeusedas well).Whenthekeystoreisbackedbysuchadevice,the privatekeydoesnotphysicallyleavetheHSMdeviceand certaincryptographicoperationsmustbeperformedonthat device. RequirediftheKeyStoreLocationparameterisdefined.If theKeyStoreLocationparameterisnull,theAliasproperty isignored. Specifiesthealiasthatpointstotheprivatekeyandits associatedcertificatechaininthekeystore.Eachlistener pointstoonealiasonthekeystore;therecanbemultiple aliasesinthesamekeystoreandmorethanonelistenercan usethesamealias.
Alias
Optional.Specifiesthenameofthedirectorythatcontains thecertificatesofthecertificationauthorities(CAs)thatthis servertrustswhenitusesthisport;forexample, config\xApps\TrustedCAs. Note: Currentlythekeystorestoresonlytheprivatekeyand itsassociatedcertificatechain,notthetrustedCA certificates.
6 7 8
Adding an FTP Port

UsinganFTPport,youcanmovefilestoandfromtheIntegrationServer.Completethe instructionsbelowtoconfigureanFTPport. To add an FTP port 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickPorts. ClickAdd Port. IntheAdd Portareaofthescreen,selectwebMethods/FTP.
101
7 Configuring Ports
ClickSubmit.TheIntegrationServerdisplaysascreenrequestinginformationabout theport.Enterthefollowinginformation: For this parameter... Port Package name Specify ThenumberyouwanttousefortheFTPport.Selecta numberthatisnotalreadyinuse. Packageassociatedwiththisport.Whenyouenablethe package,theserverenablestheport.Whenyoudisablethe package,theserverdisablestheport. Ifyoureplicatethispackage,theIntegrationServercreatesa portwiththisnumberandthesamesettingsonthetarget server.Ifaportwiththisnumberalreadyexistsonthetarget server,itssettingsremainintact.Thisfeatureisusefulifyou createanapplicationthatexpectsinputonaspecificport. Theapplicationwillcontinuetoworkafteritisreplicatedto anotherserver. Bind Address (optional) IPaddresstowhichtobindthisport.Specifyabindaddress ifyourmachinehasmultipleIPaddressesandyouwantthe porttousethisspecificaddress.Ifyoudonotspecifyabind address,theserverpicksoneforyou. TheaddressthatshouldbesentbythePORTcommand.A hostnameorIPaddresscanbespecified. Whenrunninginpassivemode,theFTPportsendsaPORT commandtotheFTPclient.ThePORTcommandspecifies theaddressandporttowhichtheclientshouldconnectto createadataconnection.IftheFTPportisbehindaNAT server,however,theaddressofthehostonwhichthe IntegrationServerrunsisnotvisibletotheFTPclient. ConsequentlythePORTcommanddoesnotcontainthe informationtheclientneedstoconnecttotheserver.To remedythissituation,youcanspecifyavalueforthe watt.net.ftpPassiveLocalAddrpropertyintheserver configurationfile(server.cnf),whichislocatedinthe IntegrationServer_directory\configdirectory(seeAppendix B, ServerConfigurationParameters). Alternatively,youcanusethePassive Mode Listen Address fieldtospecifythepassivemodeaddressforanindividual FTPport.Thatway,youcanspecifyadifferentpassivemode addressforeachFTPport.Ifanaddressisspecifiedinthe Passive Mode Listen Addressfieldandinthe watt.net.ftpPassiveLocalAddrproperty,thePORTcommand usesthevaluespecifiedinthewatt.net.ftpPassiveLocalAddr property.
Passive Mode Listen Address (optional)
102
7 Configuring Ports
6 7 8
Adding an Email Port

BysettinguponeormoreemailportsonyourIntegrationServer,youcanreceiveclient requeststhroughanemailserver(POP3orIMAP).Theclientbuildsanemailthat containsthenameoftheservicetorunandparameterstopasstotheservice.Theemail canalsocontainuserIDandpasswordinformation. Note: Passingauseridandpasswordinanemailpresentsapossiblesecurity exposure.WhiletheemailresidesonthePOP3orIMAPserver,someonemightbe abletoaccessthisinformation.Ifyoumustpassauseridandpasswordinanemail, makesuretheuseridhasminimalprivileges.
To add an email port 1 2 3 4 5 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickPorts. ClickAdd Port. IntheAdd Portareaofthescreen,selectwebMethods/Email. ClickSubmit.TheIntegrationServerdisplaystheEdit Email Client Configurationscreen requestinginformationabouttheport.Enterthefollowinginformation: For this parameter... Package Name Specify Packageassociatedwiththisport.Whenyouenablethe package,theserverenablestheport.Whenyoudisablethe package,theserverdisablestheport. Ifyoureplicatethispackage,theIntegrationServercreatesa portwiththisnumberandthesamesettingsonthetarget server.Ifaportwiththisnumberalreadyexistsonthetarget server,itssettingsremainintact.Thisfeatureisusefulifyou createanapplicationthatexpectsinputonaspecificport.The applicationwillcontinuetoworkafteritisreplicatedto anotherserver.
103
7 Configuring Ports
For this parameter... Server Information
Specify Host Name. NameofthemachineonwhichthePOP3orIMAP serverisrunning. Type. Typeofmailserver.SelectPOP3orIMAP. User Name. Usernamethatidentifiesyoutothemailserver. Password. Passwordassociatedwiththeusernamethat identifiesyoutothemailserver. Time Interval. Howoften(inseconds)theemailportistocheck forincomingemailsonthePOP3orIMAPserver. Port. Porttouseforthemailserver.ThedefaultforPOP3is110; thedefaultforIMAPis143. Log out after each mail check. ForusewithIMAPand multithreadingonly.IfyouselectYes,theIntegrationServer logsoutareadonlythreadtotheIMAPmailserverafter checkingformailonthatthread.Themainread/writethread totheIMAPserverremainsintact.IfyouselectNo,alltheread onlythreadsremainintact.SelectYesifyourIMAPserver restrictsthenumberofconnectionsitwillallowtoremain loggedin.
Security
Run services as user. IfyouselectYesintheRequire authentication within messagefield,theRun services as userfieldremainsblank becausetheIntegrationServerexpectstheusernameand passwordtobeintheemail.IfyouselectNointheRequire authentication within messagefield,youmustentertheuser underwhichtheserviceistorunontheIntegrationServer. Require authentication within message. IfyouselectYes,the IntegrationServerchecksfor$userand$passparametersin theSubjectlineoftheemail.Theusernameistheuserunder whichtheserviceistorunontheIntegrationServer.Ifyou selectNo,youmustspecifytheuserintheRun services as user fieldabove. WhenyouselectNo, appearsnexttothisfield.Click lookupandselectauser.Theusercanbeaninternalor externaluser. to
104
7 Configuring Ports
For this parameter... Message Processing
Specify Global Service (optional). Servicetobeexecutedonthe IntegrationServer.Thisfieldoverridesaservicespecifiedin theSubjectlineoftheemail. Default Service (optional). Servicetobeexecutediftheemaildoes notprovideavalidserviceintheSubjectlineandtheGlobal Servicefieldisblank. Send reply email with service output. ClickYesifyouwantthe IntegrationServertosendanyoutputgeneratedbytheservice totheoriginalsenderinanemailattachment.ClickNoifyou donotwishtodoso.Iftheoriginalemailcontainedmultiple attachments,thereplycontainsanequalnumberof attachments. Send reply email on error. ClickYesifyouwanttheIntegration Servertoreportanyerrorsthatoccurredduringservice executiontotheoriginalsenderintheBodyportionofan email.ClickNoifyoudonotwishtodoso. Delete valid messages (IMAP only). ClickYesifyouwanttodelete avalidemailfromtheIMAPserveroncetheIntegration Serverhassuccessfullyreceivedtheemail.Thissettinghelps preventemailsfromaccumulatingontheIMAPserver, possiblyaffectingdiskspaceandperformance.The IntegrationServeralwaysdeletesemailsonaPOP3server. ClickNoifyouwanttoretaintheemailsontheIMAPserver. Delete invalid messages (IMAP only). ClickYesifyouwantto deleteinvalidemailsfromtheIMAPserver.ClickNoifyoudo wanttoremovetheseemailsfromtheserver.Invalidemails arethosethatexperiencederrorsduringprocessing.This settinghelpspreventinvalidemailsfromaccumulatingonthe IMAPserver,possiblyaffectingdiskspaceandperformance. TheIntegrationServeralwaysdeletesemailsonaPOP3 server. Multithreaded processing (IMAP only). ClickYesifyouwantthe IntegrationServertousemultiplethreadsforthisport.This settingallowstheporttohandlemultiplerequestsatonceand avoidabottleneck.ClickNoifyoudonotneedthisfeature. Number of threads if multithreading is turned on. Tellsthe IntegrationServerthenumberofthreadstouseforthisport. Thedefaultis setto0.
105
7 Configuring Ports
Specify Invoke service for each part of multipart message.Specifieswhether theIntegrationServerinvokestheserviceforeachpartofa multipartmessageorjustoncefortheentiremessage. IfyouspecifyNo,theentireemailispassedtotheappropriate contenthandlerandthentothespecifiedserviceforexecution. Whenyousendanentiremultipartemail,makesurethe serverincludestheemailheadersfromthebeginningofthe message,sothatthecontenthandlerand/orserviceknows howtoprocessthecontenttypeheadersincludedineachpart oftheemail.SeeInclude email headers when passing message to content handlerbelow. IfyouspecifyYes,theIntegrationServertreatseachpartofthe messageindividually.Thatis,theIntegrationServersends eachparttothecontenthandlerandthentothespecified service.WhenyouspecifyYes,youprobablydonotwantto includetheemailheadersfromthebeginningofthemessage, becauseeachsectionhasitsownheadersthatthecontent handlerand/ortheservicealreadyknowshowtoprocess.See Include email headers when passing message to content handler below. Include email headers when passing message to content handler. SpecifieswhethertheIntegrationServerincludestheemail headerswhenpassinganemailmessagetothecontent handler.Theemailheadersaretypicallyfoundatthe beginningofanemailmessage.SpecifyYesifyouare processingamultipartmessageasasinglemessage.This ensuresthatthecontenthandlerand/orservicecanproperly processthebodyoftheemail.SpecifyNoifyouareprocessing thedifferentpartsofanemailindividually.Ifyouare processingasinglepartemail,youprobablydonotwantto includeemailheaders. Email body contains URL encoded input parameters.Specifieshow theIStreatsinputparametersitfindsinemailmessages.With thisvaluesettoYes,theISconsidersastringsuch as?one=1+two=2tobeaURLencodedinputparameter.Itthen decodesthisstringintoanIDataobject,putsitintothe pipeline,andpassesittotheservice.WiththisvaluesettoNo, theIStreatsthestringasplaintextandpassesittothe appropriatecontenthandler.
ClickSave Changes.
106
7 Configuring Ports
OnthePortsscreen,clickEdittochangetheAccessModeifnecessary.YoumaySet Access Mode to Allow by DefaultorReset to default access settings. Note: Ifyousetportaccessrestrictions,besurethewatt.net.email.validateHost serverconfigurationpropertyissettotrue,sotheIntegrationServerhonorsyour IPaccessrestrictions.
OnthePorts screen,alsocheckthelistofportstoensurethatthestatusintheEnabled columnisYes.Ifitisnot,clickNotoenabletheport
Adding an HTTP Diagnostic Port

Thediagnosticportisaspecialportthatusesthreadsfromadedicatedthreadpoolto acceptrequestsviaHTTP.Thediagnosticportusesadedicatedthreadpoolsothatyou canaccesstheIntegrationServerwhenitbecomesunresponsive. WhenyouinstalltheIntegrationServer,itautomaticallycreatesthediagnosticportat 9999.Ifanotherportisrunningat9999,theserverwilldisablethediagnosticportwhen youstarttheIntegrationServer. Note: EachIntegrationServercanhaveonlyonediagnosticport.Ifyouwanttoadda newdiagnosticport,youmustdeletetheexistingportfirst.Forinformationabout howtodeleteaport,seeDeletingaPortonpage 117. Formoreinformationaboutthediagnosticport,seeAppendix C,Diagnosingthe IntegrationServer. To add an HTTP diagnostic port 1 2 3 4 5 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickPorts. ClickAdd Port. UnderAdd Port,selectHTTP Diagnostic. ClickSubmit.
107
7 Configuring Ports
OntheEdit Diagnostic Port Configurationscreen,enterthefollowinginformation: For this parameter Port Package Name Specify Thenumberyouwanttouseforthediagnosticport.Selecta numberthatisnotalreadyinuse. Thepackageassociatedwiththisport.Thedefaultpackageis WmRoot.Whenyouenablethepackage,theserverenablesthe port.Whenyoudisablethepackage,theserverdisablesthe port. Ifyoureplicatethispackage,theIntegrationServercreatesa portwiththisnumberandthesamesettingsonthetarget server.Ifaportwiththisnumberalreadyexistsonthetarget server,itssettingsremainintact.Thisfeatureisusefulifyou createanapplicationthatexpectsinputonaspecificport.The applicationwillcontinuetoworkafteritisreplicatedto anotherserver. Note: YoucannotchangethePackage Nameassociatedwiththis port.Thediagnosticportmustalwaysbeassociatedwiththe WmRootpackage. Bind Address (optional) TheIPaddresstowhichyouwanttobindthisport.Specifya bindaddressifyourmachinehasmultipleIPaddressesand youwanttheporttouseaspecificaddress.Ifyoudonot specifyabindaddress,theserverpicksoneforyou. Howlongaconnectionrequestshouldstayinthequeuefora suspendedport,beforetherequestisrejected.Thedefaultis setto200milliseconds(ms),withamaximumpermissible valueof65535ms. Whentoclosetheconnectioniftheserverhasnotreceiveda requestfromtheclientwithinthistimeoutvalue(in milliseconds);orwhentoclosetheconnectioniftheclienthas explicitlyplacedacloserequestwiththeserver. Whetherthelistenerwillusethispoolexclusivelyfor dispatchingrequests.TheexistingIntegrationServerthread poolisaglobalthreadpool.Ifthereisaveryhighloadonthis resource,theusermayhavetowaitfortheglobalthreadpool toprocesshisrequest.However,withtheprivatethreadpool optionenabled,requestscomingintothisportwillnothaveto competewithotherserverfunctionsforthreads.
Backlog
Keep Alive Timeout
Threadpool
108
7 Configuring Ports
For this parameter Threadpool
Specify ClickEnableifyouwishtoenabletheprivatethreadpool settings.Youcanchangeoracceptthedefaultsettingsgiven below: Threadpool Min 1 Referstotheminimumnumberofthreads.The defaultissetto1. Threadpool Max 5 Referstothemaximumnumberofthreadsfor thisprivatethreadpool.Thedefaultissetto5. Threadpool Priority 5 ThisistheJavathreadpriority. Important! Thissettingmustbeusedwithextremecarebecause itwillaffecttheserverperformanceandthroughput. ClickDisableifyoudonotneedtousetheThreadpoolfeature.
7 8 9
Adding an HTTPS Diagnostic Port

Thediagnosticportisaspecialportthatusesthreadsfromadedicatedthreadpoolto acceptrequestsviaHTTP.Thediagnosticportusesadedicatedthreadpoolsothatyou canaccesstheIntegrationServerwhenitbecomesunresponsive. WhenyouinstalltheIntegrationServer,itautomaticallycreatesthediagnosticportat 9999.Ifanotherportisrunningat9999,theserverwilldisablethediagnosticportwhen youstarttheIntegrationServer. Note: EachIntegrationServercanhaveonlyonediagnosticport.Ifyouwanttoadda newdiagnosticport,youmustdeletetheexistingportfirst.Forinformationabout howtodeleteaport,seeDeletingaPortonpage 117.
109
7 Configuring Ports
Formoreinformationaboutthediagnosticport,seeAppendix C,Diagnosingthe IntegrationServer. To add an HTTPS Diagnostic port 1 2 3 4 5 6 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickPorts. ClickAdd Port. UnderAdd Port,selectHTTPS Diagnostic. ClickSubmit. OntheEdit Diagnostic Port Configurationscreen,enterthefollowinginformation: For this parameter... Port Package Name Specify Thenumberyouwanttouseforthediagnosticport.Select anumberthatisnotalreadyinuse. Thepackageassociatedwiththisport.Thedefaultpackage isWmRoot.Whenyouenablethepackage,theserver enablestheport.Whenyoudisablethepackage,theserver disablestheport. Ifyoureplicatethispackage,theIntegrationServercreates aportwiththisnumberandthesamesettingsonthetarget server.Ifaportwiththisnumberalreadyexistsonthe targetserver,itssettingsremainintact.Thisfeatureis usefulifyoucreateanapplicationthatexpectsinputona specificport.Theapplicationwillcontinuetoworkafterit isreplicatedtoanotherserver. Note: YoucannotchangethePackage Nameassociatedwith thisport.Thediagnosticportmustalwaysbeassociated withtheWmRootpackage. Bind Address (optional) TheIPaddresstowhichyouwanttobindthisport.Specify abindaddressifyourmachinehasmultipleIPaddresses andyouwanttheporttouseaspecificaddress.Ifyoudo notspecifyabindaddress,theserverpicksoneforyou. Howlongaconnectionrequestshouldstayinthequeue forasuspendedport,beforetherequestisrejected.The defaultissetto200milliseconds(ms),withamaximum permissiblevalueof65535ms.
Backlog
110
7 Configuring Ports
For this parameter... Keep Alive Timeout
Specify Whentoclosetheconnectioniftheserverhasnotreceived arequestfromtheclientwithinthistimeoutvalue(in milliseconds);orwhentoclosetheconnectioniftheclient hasexplicitlyplacedacloserequestwiththeserver. Whetherthelistenerwillusethispoolexclusivelyfor dispatchingrequests.TheexistingIntegrationServer threadpoolisaglobalthreadpool.Ifthereisaveryhigh loadonthisresource,theusermayhavetowaitforthe globalthreadpooltoprocesshisrequest.However,with theprivatethreadpooloptionenabled,requestscoming intothisportwillnothavetocompetewithotherserver functionsforthreads.ClickEnableifyouwishtoemploy theprivatethreadpoolsettings.Youcanchangeoraccept thedefaultsettingsgivenbelow: Threadpool Min 1 Referstotheminimumnumberofthreads. Thedefaultissetto1. Threadpool Max 5 Referstothemaximumnumberofthreads forthisprivatethreadpool.Thedefaultissetto5. Threadpool Priority 5 ThisistheJavathreadpriority. Important! Thissettingmustbeusedwithextremecare becauseitwillaffecttheserverperformanceand throughput. ClickDisableifyoudonotneedtousetheThreadpool feature.
Threadpool
Client Authentication
ThetypeofclientauthenticationyouwanttheIntegration Servertoperform.SeeChapter 13,Authenticating Clientsformoreinformation. Note: FTPSclientsarealwayspromptedforauseridand password. None. Theclientlogsinastheuserspecifiedonthe userid/passwordprompt. Request Client Certificates. Theserverrequestsclient certificatesforallrequeststhatcomeinonthisFTPSport, butacertificateisnotrequiredforlogin.
111
7 Configuring Ports
Specify Require Client Certificates. Theserverrequiresclient certificatesforallrequeststhatcomeinonthisFTPSport. Ifnocertificateisprovided,orifthecertificateisnot trusted,theIntegrationServerrejectstherequest. Bydefault,theIntegrationServerdoesnotperform certificatemappingforFTPSports.Tousethisfeature,you mustsetthewatt.net.ftpUseCertMapconfiguration propertytotrue.Formoreinformationabouthowclient authenticationworksforFTPSports,seeChapter 13, AuthenticatingClients.Formoreinformationabout certificatemapping,seeImportingaClientCertificate andMappingIttoaUseronpage 186.
Servers Certificate
Optional.Pathandfilenameofthefilethatcontainsthe IntegrationServersdigitalcertificate.Specifyavaluehere onlyifyouwantthisporttopresentadifferentserver certificatefromtheonespecifiedontheCertificatesscreen. Optional.Pathandfilenameofthefilethatcontainsthe certificateforthecertificateauthoritythatsignedthe IntegrationServersdigitalcertificate. Optional.Pathandfilenameofthefilethatcontainsthe privatekeyoftheprivate/publickeypairassociatedwith theIntegrationServersdigitalcertificate.Ifyouleavethis fieldblank,theIntegrationServerusestheprivatekey specifiedontheCertificatesscreen. Optional.Nameofthedirectory(relativetotheserver home;orfullyqualifiedpath;ornetworkpaththat containsthedigitalcertificatesofcertificateauthorities trustedbythisserver,forexampleconfig\cas.Ifyouleave thisfieldblank,theIntegrationServerusesthetrusted authoritydirectoryspecifiedontheCertificatesscreen.If thetrustedauthorityfieldisblankontheCertificatesscreen aswell,theserverthenchecksthevalueofthe
Authoritys Certificate
Private Key
property.IfthevalueisTrue (default),theservertrustsall certificates.IfthevalueisFalse,theservertrustsno certificates. ---Or--KeyStore Location Optional.Thelocationondiskwherethekeystoreis located(foranHSM/smartcardbackedkeystore,afile existsondiskbutdoesnotcontaintheactualprivatekey).
112
7 Configuring Ports
For this parameter... KeyStore Password
Specify Optional.Thepasswordwithwhichthekeystoreis protected.Iftheprivatekeyandcertificatechainarestored onanHSMdevice,thispropertymustmatchthepassword withwhichthecardwasprotected(forexample,for nCipherastheHSMprovider,thispropertymustmatch theOCS(OperatorCardSet)passwordforthecard). Optional.Thetypeofthekeystore.Differentvendors supportdifferenttypesofkeystore;forexample,the defaultSUNkeystoreimplementationisoftypejks (nCipheralsousesthistype). Withinthisproperty,thenameinparenthesesisthename oftheSecurityProviderthatwillprovidesupportforthe keystoretype.Ifthedesiredproviderisnotlistedinthe dropdownlist,youcanadditbyclickingtheAddnew SecurityProviderlink.Formoreinformationabouthow toaddasecurityprovider,seeAddingaSecurity Provideronpage 119. Aslongasaportwiththegivenproviderexists,youwill nothavetomanuallyreregisterthesecurityprovider.If thelastportwhichusesthisproviderisdeletedandthe IntegrationServerisrestarted,youmustreregisterthis securityproviderbeforeusingitforaport. Important! TheIntegrationServersupportsJKSand PKCS#12keystoretypesonly.Otherkeystoretypesmay workwithIntegrationServerbutarenotsupported.
KeyStore Type
HSM Based Keystore
Optional.Indicateswhetherornotthekeystoreisbacked byanHSMbasedkeystore(asmartcarddevicecanbe usedaswell).Whenthekeystoreisbackedbysucha device,theprivatekeydoesnotphysicallyleavetheHSM deviceandcertaincryptographicoperationsmustbe performedonthatdevice. RequirediftheKeyStoreLocationparameterisdefined.If theKeyStoreLocationparameterisnull,theAliasproperty isignored. Specifiesthealiasthatpointstotheprivatekeyandits associatedcertificatechaininthekeystore.Eachlistener pointstoonealiasonthekeystore;therecanbemultiple aliasesinthesamekeystoreandmorethanonelistenercan usethesamealias.
Alias
113
7 Configuring Ports
For this parameter... Trusted Authority Directory
Specify Optional.Specifiesthenameofthedirectorythatcontains thecertificatesofthecertificationauthorities(CAs)that thisservertrustswhenitusesthisport;forexample, config\xApps\TrustedCAs. Note: Currentlythekeystorestoresonlytheprivatekey anditsassociatedcertificatechain,notthetrustedCA certificates.
7 8 9
Suspending an HTTP/HTTPS Port

Bydefault,theIntegrationServeracceptsportconnectionrequestsassoonasitreceives them.Ifyoudonotwishtoaccepttheporttoacceptanymoreconnectionsordispatch anymorerequests,youcanusethenewlyavailablesuspendfeatureontheIntegration ServerAdministrator. Note: Ifarequestismadeonthesuspendedlisteningport,thelistenerwillnotaccept anymoreconnectionsordispatchanymorerequests,ifthebacklogqueueisnot enabled.However,ifthebacklogqueueisenabled,andisnotfull,theconnectionis queued.Ifyoudeleteordisableasuspendedport,thequeuedconnectionswillget released. To suspend an HTTP or HTTPS port 1 2 3 4 5 6 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickPorts. Youwillseeainthemain areaofthescreen. InthePort Listtable,clickEditintheAdvancedcolumnfortheportyouwantto suspend. UnderListener Controls,selecttheSuspendcheckbox. ClickApplytosaveyourchanges. ClickReturn to PortstoreturntotheSecurity > Portsscreen.
114
7 Configuring Ports
Resuming an HTTP/HTTPS Port

Youcanresumeaporttorevertbacktothedefaultmodeofacceptingportconnections anddispatchingmessagesontheIntegrationServer. To resume an HTTP or HTTPS port 1 2 3 4 5 6 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickPorts. InthePort Listtable,clickEditintheAdvancedcolumnfortheportyouwanttoresume. UnderListenerControls,selecttheResumecheckbox. ClickApply tosaveyourchanges. ClickReturn to PortstoreturntotheSecurity > Portsscreen.
Specifying an FTP/FTPS Port Range

TheIntegrationServerprovidesFTPandFTPSlistenersthatlistenforFTP/FTPSclient dataconnectionsonanyfreeport.ForFTPS,thisportusagemethodrequiresallportsto beopenonthefirewall,asituationthatfirewalladministratorsprefertoavoid. YoucanspecifyarangeofportnumbersfortheFTP/FTPSlistenertousewithaclient dataconnectionthatusespassivetransfermode(PASV). To specify a port range for FTP and FTPS listeners 1 2 3 StartIntegrationServerandlogontotheIntegrationServerAdministrator. IntheIntegrationServerAdministrator,selectExtendedintheSettingsareaofthe Navigationpanel. OntheSettings Extendedpage,determineifthefollowingsettingsaredisplayedin theExtended Settingslist: watt.net.ftpPassivePort.min watt.net.ftpPassivePort.max Iftheyarepresent,gotostep4.Ifthesettingsarenotvisible: a b ClickShow and Hide Keys. OntheSettings Extended Show and Hide Keyspage,lookforthetwosettings.If thesettingsarepresent,selectthecheckboxnexttoeachoneandclickSave Changes.Ifthesettingsarenotvisible,clickReturn to Extended Settings.
115
7 Configuring Ports
OntheSettings
Extendedpage,clickEdit Extended Setting,anddooneofthefollowing:
Note: Extendedsettingsdefinitionsarecasesensitive. Ifthetwosettingsarepresent,changetheirvaluesbytypinganewextended settingvalueforeachsettingintheExtended Settingstextbox,asdescribedbelow. Ifthetwosettingsarenotpresent,typeeachofthetwoextendedsettingsand theirvaluesintheExtended Settingstextbox,asdescribedbelow. For this extended setting... watt.net.ftpPassivePort.min watt.net.ftpPassivePort.max Enter this value... Minimum_Port_Number Maximum_Port_Number
ValuesforMinimum_Port_NumberandMaximum_Port_Numberareportnumbers from1to65534.Whenaportrangeisspecifiedwiththeseproperties,onlythe portswithinthespecifiedminimumandmaximumportrange(inclusive)are usedasthelisteningportsforincomingFTP/FTPSclientdataconnections.You mustspecifybothaminimumandmaximumsetting. Operationalconsiderations: Ifbothpropertiesarenotpresentorundefined,FTP/FTPSlistenerscontinue thepreviousbehavioroflisteningonanyfreeport. Ifthevaluespecifiedforwatt.net.ftpPassivePort.minislessthan1,adefault valueof1isused.Ifthevaluespecifiedforwatt.net.ftpPassivePort.maxis greaterthan65534,adefaultvalueof65534isused.Whenbothofthese conditionsexistsimultaneously,FTP/FTPSlistenerscontinuetheprevious behavioroflisteningonanyfreeport. AnerrormessageisreturnedtotheFTP/FTPSclientonthecommandchannel whenthespecifiedvaluesdonotfallwithintheexpectedrange.Forexample, ifoneofthepropertiesisnotdefined,ifthewatt.net.ftpPassivePort.minvalue islargerthanthewatt.net.ftpPassivePort.maxvalue,orifoneoftheproperties isnotavalidnumber. Anerrormessageisalsoreturnedwhenalltheportsinthespecifiedport rangeareinuse. Specificdetailsoftheerrormessagesareavailableinthe serverYYYYMMDD.logfile. 5 ClickSave Changes.
RestartingtheIntegrationServerisnotrequired.Youcanmodifytheportrange propertiesintheIntegrationServerAdministratoratanytime.
116
7 Configuring Ports
Changing the Primary Port

TheprimaryportisanHTTPorHTTPSportthatyoudesignateastheserversmain listeningport.Theserverdoesnotreservetheprimaryportforanyspecialpurpose. However,itwillneverallowtheprimaryporttobedeleted,whichguaranteesthatat leastoneportisalwaysavailable. Theprimaryportnumberisalsotheportnumberthatclientsreceivewhentheyquery yourserverwatt.server.portproperty.Bydefault,theserverdesignatesanHTTPportat 5555astheprimaryport. To change the primary port 1 2 3 4 5 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickPorts. ClickChange Primary Port. IntheSelect New Primary Port areaofthescreen,inthePrimary Portlist,selecttheport youwanttomaketheprimaryport.ClickUpdate. OnthePorts screen,checkthelistofportstoensurethatthestatusintheEnabled columnis (enabled).Ifitisnot,clicktheicontoenabletheport.
Deleting a Port
Ifyounolongerneedaport,youcandeleteit. Important! Youcannotdeletetheprimaryportdefinedfortheserver. To delete a port 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickPorts. LocatetheportinthePort List,andclickthe iconintheDeletecolumn.Theserver displaysadialogboxthatpromptsyoutoconfirmyouraction.ClickOKtoconfirm thatyouwanttodeletetheport.
117
7 Configuring Ports
Editing a Port
Afteraddingaport,youcanedittheportconfiguration.Theportmustbedisabledbefore youcanedittheconfiguration. To edit a port 1 2 3 4 5 6 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickPorts. Locatetheportyouwanttoeditandclickontheportnumber. ClickEdit <port type> Port Configuration. Updatetheinformationfortheport. ClickSave Changes.
Enabling/Disabling a Port
Ifyouwanttotemporarilypreventtheserverfromacceptingrequestsononeofitsports, youcandisablethatport.Thisactionblocksincomingrequestsfromreachingtheserver. Whenaportisdisabled,clientsreceiveanerrormessagewhentheyissuerequeststoit. Later,youcanenabletheport.Ifyoushutdownandrestarttheserver,theportremains disableduntilanadministratorenablesit.Disablingaportisaconvenientwayto eliminatedeveloperaccesstoanIntegrationServeronceitgoesintoproduction. Anotherwaytoenableordisableaportistoenableordisablethepackageassociated withtheport.Youcanassociateapackagewithaspecificportsothatwhenyoureplicate thepackage,itcontinuestouseaportwiththesamenumberonthenewserver.Whena packageisassociatedwithaport,enablingthepackageenablestheportanddisablingthe packagedisablestheport. Important! Youmustleaveatleasttheprimaryportenabled.
To disable a port 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickPorts. LocatetheportinthePortList,andclickthe iconintheEnabledcolumntodisable theport.Theserverdisplaysadialogboxthatpromptsyoutoverifyyouraction. ClickOKtoverifyyouwanttodisabletheport. Theserverreplacesthe iconwithNotoindicatethattheportisnowdisabled.
118
7 Configuring Ports
To enable a port 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickPorts. LocatetheportinthePort List,andclickNointheEnabledcolumntoenabletheport. Theserverdisplaysadialogboxthatpromptsyoutoverifyyouraction.ClickOKto verifyyouwanttoenabletheport. TheserverreplacestheNo withthe icontoindicatethattheportisnowenabled.
Adding a Security Provider

IfyouwanttoaddanHTTPSorFTPSportwithalistenerthatwilluseaprivatekeyand certificatechainresidinginakeystoreandthekeystoreismanagedbyanonstandard SecurityProvider,youmayneedtoaddthatSecurityProvidertotheIntegrationServer Administrator. WhenspecifyingkeystoreinformationintheHTTPSorFTPSportinformationscreen,a nonstandardSecurityProvidermaynotappearintheKeyStoreTypeparameterdrop downlist.IftheSecurityProviderthatyouwanttousenotappearinthelist,usethe AddNewSecurityProviderlinktoaddtheSecurityProvider. To add a security provider 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickPorts. ClickAdd Security Provider. IntheAdd Security Provider areaofthescreen,intheSecurity Provider Classfield,enter thefullyqualifiednameofthesecurityproviderclassforthesecurityprovideryou wanttoadd.Forexample,thenameofnCipherssecurityprovideris com.ncipher.provider.km.nCipherKM. ClickAdd Provider. TheserveraddsthesecurityprovidertotheKeyStoreTypedropdownlist.Youcan selecttheproviderfromthelistwhensettingupanHTTPSorFTPSport.
119
7 Configuring Ports
120
Configuring Document Stores

122 123 124 126 127 127 128 129
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring the Default Document Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring the Trigger Document Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Maintaining Inbound Document History for Received Documents . . . . . . . . . . . . . . . . . . . . . . . . Enabling Inbound Client-Side Queuing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring the Outbound Document Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Selecting a User Account for Invoking Services Specified in Broker/Local Triggers . . . . . . . . . . Managing the Document History Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
121
8 Configuring Document Stores
Overview
TheIntegrationServerusesdocumentstorestosavedocumentstodiskortomemory whilethedocumentsareintransitorwaitingtobeprocessed.IntegrationServer maintainsthreedocumentstoresforpublisheddocuments. Default document store.Thedefaultdocumentstorecontainsdocumentsdeliveredto theclientIDoftheIntegrationServer.WhentheIntegrationServerretrieves documentsdeliveredtoitsclientID,theserverplacesthedocumentsinthedefault documentstore.Documentsremaininthedefaultdocumentstoreuntilthe dispatcherdetermineswhichtriggerssubscribetothedocument.Thedispatcherthen movesthedocumentstothetriggerqueuesforthesubscribingtriggers. Trigger document store.Thetriggerdocumentstorecontainsdocumentswaitingtobe processedbyBroker/localtriggers.Theserverassignseachtriggeraqueueinthe triggerdocumentstore.Adocumentremainsinthetriggerqueueuntiltheserver successfullyprocessesthedocument. Outbound document store.Theoutbounddocumentstorecontainsdocumentswaiting tobesenttotheBroker.IntegrationServerplacesdocumentsintheoutbound documentstorewhentheconfiguredBrokerisnotavailable.Whentheconnectionto theBrokerisrestored,theserveremptiestheoutbounddocumentstorebysending thesaveddocumentstotheBroker. UsingtheIntegrationServerAdministrator,youcanconfigurepropertiesforeach documentstore.Forexample,youcandeterminethestorelocationsandtheinitialstore sizes.Youcanalsodeterminewhethertheinbounddocumentstoresarestoredondiskor inmemory,howlongdocumentstoresmaintainadocumenthistory,andhowquicklythe serverdrainstheoutbounddocumentstore. Thefollowingsectionsprovidemoreinformationaboutconfiguringdocumentstores. Important! Aspartofconfiguringyourservertopublishandsubscribetodocuments, youmightneedtoincreasetheminimumandmaximumheapsize.Theheapsize indicateshowmuchmemoryisallottedforserverprocesses.Toedittheheapsize, shutdowntheserver,andopentheserver.bat orserver.shusingatexteditor.Set JAVA_MIN_MEMtotheminimumheapsizeandsetJAVA_MAX_MEMtothe maximumheapsize.Bydefault,theminimumheapsizeis256MBandthemaximum heapis512MB.Yourcapacityplanningandperformanceanalysisshouldindicate whetheryouneedtosethighermaximumandminimumheapsizevalues.
122
Configuring the Default Document Store

Thedefaultdocumentstorecontainspublisheddocumentsdelivereddirectlytotheclient IDoftheIntegrationServer.Documentsremaininthedefaultdocumentstoreuntilthe dispatchermovesthedocumenttothetriggerqueuesforthesubscribingBroker/local triggers. Whenyouconfigurethedefaultdocumentstore,youspecifythedocumentstorelocation andtheinitialsizeofthedocumentstore.Youcanalsosetthedocumentstorecapacity andsetarefillleveltoindicatewhentheservershouldrefillthedefaultdocumentstore. To configure the default document store 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickResources. Click Store Settings,andthenclickEdit Document Store Settings. SettheDefault Document Store parametersasfollows: For this parameter Specify... Store Location Thelocationofthedefaultdocumentstore.Bydefault,the IntegrationServersavesdocumentstoresinthefollowing directory:
\IntegrationServer_directory\DocumentStore
Ifyouwanttosavethedefaultdocumentstoreinadifferent location,specifythedirectoryinthisfield.Ifthedirectorydoesnot exist,theservercreatesit. Important! Makesurethatyouhavewriteaccesstothespecified directoryandthatthedirectorydoesnotcontainanycharacters consideredillegalbyyouroperatingsystem. Initial Store Size (MB) Theamountofdiskspaceallocatedtothedefaultdocumentstore atstartup.Thedefaultstoreautomaticallyincreaseswhenit receivesdatathatexceedstheinitialsize.Thedefaultsizeis25MB. WhensettingtheInitial Store Size,considerthesizeandvolumeof documentsthatyouexpecttobedeliveredtothedefault documentstore.Ifyouexpectlargedocumentsorahighvolume ofdocuments,considerincreasingtheInitial Store Size. Important! Makesurethatthereisenoughfreediskspaceonthe IntegrationServermachinetoaccommodatetheinitialsizesofthe defaultdocumentstore,thetriggerdocumentstore,andtheXA recoverystore.
123
For this parameter Specify... Capacity Themaximumnumberofdocumentsinthedefaultdocument store.Thedefaultis10documents. TheCapacitymustbegreaterthantheRefill Level. IfyousetCapacityto0,theserverautomaticallysuspendstheRefill Level.IfyousettheCapacityfieldto0,theserverdisplays SuspendednexttothefieldontheSettings > Resources > Store Settingspage. Note: TheCapacityfielddisplaysBrokerNotConfiguredifthere isnotaBrokerconfiguredfortheserver. Refill Level Thenumberofunprocesseddocumentsthatremaininthedefault documentstorebeforetheIntegrationServerretrievesmore documentsfromtheBroker. Forexample,ifyouassignthedefaultdocumentstoreaCapacityof 10andaRefill Levelof4,theserverinitiallyretrievesten documents.Whenonlyfourdocumentsremaintobeprocessedin thedefaultdocumentstore,theserverretrievessixmore documents.Ifsixdocumentsarenotavailable,theserverretrieves asmanyaspossible. Thedefaultrefilllevelis4documents. TheRefill LevelmustbelessthanCapacity.IfyousetCapacityto0, theserverautomaticallysuspendstheRefill Level. Note: TheRefill Level fielddisplaysBrokerNotConfiguredif thereisnotaBrokerconfiguredfortheserver.
Note: Anasterisk(*)nexttoafieldindicatesthatyouneedtorestarttheserverfor changestotakeeffect.
Configuring the Trigger Document Store

Thetriggerdocumentstorecontainstriggerqueuesinwhichtheserverkeepsdocuments waitingforprocessing.Adocumentremainsinthetriggerqueueuntiloneofthe followingoccurs: TheIntegrationServersuccessfullyexecutesthetriggerservicespecifiedinthetrigger conditionsatisfiedbythedocument. TheIntegrationServerdiscardsthedocumentbecausethedocumentdoesnotsatisfy anyconditionsinthetrigger.
124
TheIntegrationServerdiscardsthedocumentbecauseitisaduplicateofonealready processedbythetrigger.Thiscanoccuronlyifthetriggerisconfiguredforexactly onceprocessing. TheIntegrationServercannotdeterminewhetherthetriggerprocessedthedocument previously,assignsthedocumentastatusofInDoubt,andinstructstheaudit subsystemtologthedocument.Thiscanoccuronlyifthetriggerisconfiguredfor exactlyonceprocessing. Whenyouconfigurethetriggerdocumentstore,youspecifythelocationofthestoreand theinitialsizeofthestore. Note: Toconfigurethedocumentcapacityandrefilllevelforeachtriggerqueue,use webMethodsDevelopertoeditthetriggersettings.Formoreinformationabout triggersettingsandtriggerdocumentstoresforBroker/localtriggers,seePublish SubscribeDevelopersGuide.Tomanagetriggerdocumentstorecapacityforalltriggers atruntime,seeDecreasingtheCapacityofTriggerDocumentStoresonpage 365. To configure the trigger document store 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickResources. Click Store Settings,andthenclickEdit Document Store Settings. SettheTrigger Document Store parametersasfollows: For this parameter Store Location Specify... Thelocationofthetriggerdocumentstore.Bydefault,the IntegrationServersavesthetriggerdocumentstoreinthe followingdirectory:
\IntegrationServer_directory\DocumentStore
Ifyouwanttosavethetriggerdocumentstoreinadifferent directory,specifythedirectoryinthisfield.Ifthedirectory doesnotexist,theservercreatesit. Important! Makesurethatyouhavewriteaccesstothespecified directoryandthatthedirectorydoesnotcontainany charactersconsideredillegalbyyouroperatingsystem.
125
For this parameter Initial Store Size (MB)
Specify... Theamountofdiskspaceallocatedtothetriggerdocument storeatstartup.Thetriggerdocumentstoreautomatically increaseswhenitreceivesdatathatexceedstheinitialsize.The defaultsizeis35MB. Important! Makesurethatthereisenoughfreediskspaceonthe IntegrationServermachinetoaccommodatetheinitialsizesof thedefaultdocumentstore,thetriggerdocumentstore,and theXArecoverystore.
Note: Anasterisk(*)nexttoafieldindicatesthatyouneedtorestarttheserverfor changestotakeeffect.
Maintaining Inbound Document History for Received Documents

IftheIntegrationServerconnectstoaBrokerversion6.0.1,youcanconfiguretheInbound Document Historysettingtomaintainahistoryofdocumentsreceivedbytheserver.This instructstheservertoperformaverybasicformofduplicatedetectionforalltriggers. IftheIntegrationServerconnectstoaBrokerversion6.1orlater,youcanconfigure duplicatedetectiononapertriggerbasis.Forinformationaboutconfiguringduplicate detectionforBroker/localtriggersusingversion6.1orlateroftheIntegrationServer,see PublishSubscribeDevelopersGuide. InaclusterofIntegrationServersconnectedtoaBrokerversion6.0.1,eachIntegration Serverintheclustermaintainsitsowninbounddocumenthistoryinformation.Thatis, theinbounddocumenthistoryinformationisnotsharedacrossthecluster. Note: TheInbound Document History (minutes)fieldcanbesetonlyiftheIntegration ServerconnectstoaBrokerversion6.0.1.Thefieldisnotavailableiftheserver connectstoa6.1orlaterversionoftheBroker.Fordetailedinformationabout configuringinbounddocumenthistory,seethe6.0.1versionofthewebMethods IntegrationServerAdministratorsGuide.
126
Enabling Inbound Client-Side Queuing

IftheIntegrationServerconnectstoa6.0.1versionoftheBroker,youcanuseclientside queueing.Whenclientsidequeuingisenabled,theIntegrationServerstoresreceived documentsondiskandacknowledgesdocumentstothewebMethodsBroker immediatelyafterreceiptandstorage.Whenclientsidequeuingisdisabled,the IntegrationServerstoresreceiveddocumentsinmemoryandacknowledgesdocuments tothewebMethodsBrokerafterprocessingcompletes. Note: ClientsidequeuingisnotavailablewhentheIntegrationServerconnectstoa 6.1orlaterversionoftheBroker.Forinformationaboutusingclientsidequeuing witha6.0.1versionoftheBroker,seethe6.0.1versionofthewebMethodsIntegration ServerAdministratorsGuide.
Configuring the Outbound Document Store

Theoutbounddocumentstorecontainsguaranteeddocumentspublishedbytheserver whentheconfiguredBrokerisnotavailable.AftertheconnectiontotheBrokeris reestablished,theserversendsthedocumentsintheoutbounddocumentstoretothe Broker.Tomaintainpublicationorder,theserverplacesallpublisheddocuments (guaranteedandvolatile)intheoutbounddocumentstorebeforesendingthedocuments totheBroker.TheserverresumessendingdocumentsdirectlytotheBrokerafterthe outbounddocumentstoreisempty. Note: YoucanconfigureIntegrationServertothrowaServiceExceptionwhenthe Brokerisunavailableinsteadofplacingpublisheddocumentsintheoutbound documentstore.Formoreinformation,seethewatt.server.publish.useCSQ parameteronpage 434. Youcanconfigurehowquicklytheserveremptiestheoutbounddocumentstoreby settingtheMaximum Documents to Send per TransactionparameterontheSettings > Resources > Store Settings > Edit Document Store Settingspage.Bydefault,thisparameterissetto25 documents.Toemptytheoutbounddocumentstoremorequickly,increasethenumberof documentssentpertransaction.Keepinmindthattheamountofmemoryneededto senddocumentsincreaseswiththenumberofdocumentssentforeachtransaction.Ifyou wanttouselessmemorytoemptytheoutbounddocumentstoreandcanallowthe outbounddocumentstoretoemptymoreslowly,decreasethenumberofdocumentssent foreachtransaction.However,itisadvisabletodraintheoutbounddocumentstoreas quicklyaspossiblebecausetheserverperformsmorequicklyandusesfewerresources whenpublishingdocumentsdirectlytotheBroker. Tip! YoucanusetheCurrent Documents in Outbound Storefieldtomonitorthenumberof documentsintheoutbounddocumentstoreandhowquicklytheserverdrainsthe store.
127
To configure how quickly the server empties the outbound document store. 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickResources. Click Store Settings,andthenclickEdit Document Store Settings. UnderOutbound Document Store,intheMaximum Documents to Send per Transaction,type thenumberofdocumentstheservershouldsendfromtheoutbounddocumentstore totheBrokerforeachtransaction. IfthereisnoconfiguredBroker,theIntegrationServerAdministratordisplays BrokerNotConfigurednexttothefieldname.
Setting the Capacity of the Outbound Document Store

Bydefault,theoutbounddocumentstorecancontainamaximumof500,000documents. Aftertheoutbounddocumentstorereachescapacity,theserverblocksorpausesany threadsthatareexecutingservicesthatpublishdocuments.Thethreadsremainblocked untiltheserverbeginsdrainingtheoutbounddocumentstore. Thewatt.server.control.maxPersistserverparameterdeterminesthecapacityofthe outbounddocumentstore.IfyouplantobringtheBrokerdownforanextendedtime period,considereditingthisparametertolowerthecapacityoftheoutbounddocument store.Ifyoukeeptheoutbounddocumentstoreatthedefaultcapacity,andtheBroker becomesunavailable,itispossiblethatstoringoutbounddocumentscouldexhaust memoryandcausetheservertofail.Iftheoutbounddocumentstorehasalowercapacity, theserverwillblockthreadsinsteadofcontinuingtousememorybystoringdocuments.
Selecting a User Account for Invoking Services Specified in Broker/Local Triggers

WhenaclientinvokesaserviceviaanHTTPrequest,theIntegrationServerchecksthe credentialsandusergroupmembershipoftheclientagainsttheExecuteACLassignedto theservice.TheIntegrationServerperformsthischecktomakesuretheclientisallowed toinvokethatservice.Inapublishandsubscribesituation,however,theIntegration Serverinvokestheservicewhenitreceivesadocumentratherthanasaresultofaclient request.BecausetheIntegrationServerdoesnotassociateusercredentialswitha publisheddocument,youcanspecifytheuseraccountfortheIntegrationServertouse wheninvokingservicesassociatedwithBroker/localtriggers. YoucaninstructtheIntegrationServertoinvokeaserviceusingthecredentialsofoneof thepredefineduseraccounts(Administrator,Central,Default,Developer,Replicator). Youcanalsospecifyauseraccountthatyouoranotherserveradministratordefined. WhentheIntegrationServerreceivesadocumentthatsatisfiesatriggercondition,the IntegrationServerusesthecredentialsforthespecifieduseraccounttoinvoketheservice specifiedinthetriggercondition.
128
Makesurethattheuseraccountyouselectincludesthecredentialsrequiredbythe executeACLsassignedtotheservicesassociatedwithtriggers.Forexample,suppose thatyouspecifyDeveloperastheuseraccountforinvokingservicesintriggers.The receiveCustomerInfotriggercontainsaconditionthatassociatesapublishabledocument typewiththeserviceaddCustomer.TheaddCustomerservicespecifiesReplicatorforthe ExecuteACL.Whenthetriggerconditionismet,theaddCustomer servicewillnotexecute becausetheusersettingyouselected(Developer)doesnothavethenecessarycredentials toinvoketheservice(Replicator). To specify a user account to execute a service in a trigger condition 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickResources. ClickStore Settings,andthenclickEdit Document Store Settings. IntheTrigger Document Storeareaofthescreen,intheUserfield,selecttheuseraccount whosecredentialstheIntegrationServerusestoexecuteaservicespecifiedina triggercondition.Theusercanbeselectedfromacentralorexternaldirectory. EachpredefineduserprovidesdifferentsecurityaccesstotheIntegrationServer.The defaultuserisAdministrator. Administrator.UsedtoaccesstheIntegrationServerAdministratortoconfigureand managetheserver. Default.Usedwhentheclientdoesnotsupplyausernameandpassword. Developer.UsedtoconnecttotheserverfromthewebMethodsDeveloperto create,modify,anddeleteservicesthatresideontheserver. Replicator.Usedduringpackagereplication. 5 Aftereditingthedocumentstoresettings,clickSave Changes.
Managing the Document History Database

Thedocumenthistorydatabasemaintainsarecordofguaranteeddocumentsprocessed bytriggers.Thedatabasekeepsadocumenthistoryonlyfortriggersthatspecifythat documenthistoryshouldbeusedaspartofduplicatedetection.IntegrationServeradds entriestothedocumenthistorydatabasewhenatriggerservicebeginsexecutingand whenitexecutestocompletion(whetheritendsinsuccessorfailure). Tokeepthesizeofthedocumenthistorydatabasemanageable,theIntegrationServer periodicallyremovesexpiredrowsfromthedatabase.ThevalueofthetriggersHistory time to livepropertydetermineshowlongthedocumenthistorydatabasemaintainsan entryforaprocesseddocument. TheIntegrationServerprovidesascheduledservicetoremoveexpiredentriesfromthe database.Bydefault,thewm.server.dispatcher:deleteExpiredUUID serviceexecutesevery10 minutes.Youcanchangethefrequencywithwhichtheserviceexecutes.Forinformation
129
abouteditingscheduledservices,seeSchedulingServicestoExecuteatSpecifiedTimes onpage 339. YoucanalsoclearallexpiredentriesfromthedatabaseatanytimebyclickingtheRemove Expired Document History EntrieslinkontheSettings > Resources > Exactly Once Statisticspage. UsingtheRemove Expired Document History Entrieslinktoclearexpiredentriesdoesnot affectthenextscheduledexecutiontimeforthewm.server.dispatcher:deleteExpiredUUID service. Note: TheExactly Once StatisticspagealsodisplaysahistoryoftheInDoubtor Duplicatedocumentsreceivedbytriggersforwhichexactlyonceprocessingis configured.YoucanusetheClear All Duplicate or In Doubt Document Statisticslinkonthis pagetoremovethecurrentlydisplayedstatistics.
130
Connecting Integration Server to Broker

132 132 132 134
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Establishing the Primary Port for Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring an Integration Server-to-Broker Server Connection . . . . . . . . . . . . . . . . . . . . . . . . . Specifying the Keep-Alive Mode for the Broker Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . .
131
9 Connecting Integration Server to Broker
Overview
AsbackboneofthewebMethodsproductsuiteenterprisesolution,theBrokersroleisto managetheroutingofdocumentsbetweenapplicationsrunningondifferentIntegration Servers.ForanIntegrationServertojoininthisprocess,itmustfirstbeconfiguredto connecttoBroker.
Establishing the Primary Port for Integration Server

Itisimportanttoestablishtheprimaryportforyourserverbeforeconnectingyourserver totheBroker.Ifyouchangetheserversprimaryportnumberafterconfiguringthe Broker,theBrokerclientforyourIntegrationServermaybecomeunsynchronizedwith yourIntegrationServersconfiguration. IfyouchangetheserversprimaryportafterconnectingtotheBroker,performthe followingstepstoresynchronizeyourBrokerclientstotheIntegrationServersnewport configuration: 1 2 3 UsingtheBrokeruserinterface,deletetheclientsthatreflecttheserversoriginal primaryportnumber,forexample10.3.33.129_5555_DefaultClient. Deletethedispatch.cnffilefromtheIntegrationServer_directory\configdirectory. ReconfiguretheservertoconnecttotheBroker,usingtheproceduredescribedinthe followingsection.
Configuring an Integration Server-to-Broker Server Connection

Beforeconfiguringaconnection,youneedtoknowinformationaboutBrokersuchasthe hostname,theBrokername,andtheclientgrouptowhichtheIntegrationServerwill belong.Inaddition,youneedtoknowwhethertheIntegrationServerwillbeconnecting throughtheBrokerServersSSLornonSSLport. To connect Integration Server to a Broker Server 1 2 3 4 OpentheIntegrationServerAdministrator. IntheSettingsmenuoftheNavigationpanel,clickMessaging. UnderBroker Configuration,clickBroker Settings. ClickEdit Broker Settings.
132
ClickConfiguredandfilloutthefollowingfields,asshownbelow.Ifyouare configuringanSSLconnection,clickUse SSLtoenabletheSSLparameters. For this parameter Broker Host Broker Name Client Group Specify Name(DNSname:portoripaddress:port)ofthemachineon whichtheBrokerServerresides. NameoftheBrokerasdefinedontheBrokerServer.The defaultnameisBroker #1. BrokerclientgrouptowhichthisIntegrationServerbelongs. Aclientgroupdefinesasinglesetofpropertiesandaccess permissionsassignedtooneormoreclients(here, IntegrationServers)onasingleBroker.Ifthespecifiedclient groupdoesnotexist,theIntegrationServercreatesitonthe namedBrokeruponestablishingitsinitialconnection. Important! Brokersdonotsharecanpublishandcan subscribepermissionsacrossclientgroups.Ifyouswitchan IntegrationServerfromoneclientgrouptoanother,you mustrestarttheIntegrationServerandsynchronizeall publishabledocumenttypeswiththeBroker.Next,you mustshutdowntheserveranduseMywebMethodsto deletealloftheBrokerclientscreatedfortheserverwiththe changedclientgroup.Restarttheserverwiththechanged clientgroup. Client Prefix AstringthatidentifiestheIntegrationServertotheBroker. Bydefault,theserverusesitslicensekeyfortheprefix.For easeofuse,youmaywanttoreplaceitwithafriendlyname. TheBrokerManagerdisplaysthisprefixforeachclientit createsfortheserver.(TheBrokercreatesmultipleclientsfor eachserverthatconnectstoit.) IfyourIntegrationServerbelongstoacluster,makesureall serversintheclusterusethesameclientprefix. Keystore ThefullpathtothisIntegrationServerskeystorefile.A keystorefilecontainsthecredentials(privatekey/signed certificate)thatanentityneedsforSSLauthentication.Ifthe BrokerServerrequiresanSSLconnection,thenthe informationinthisfileisusedtoauthenticatetheIntegration ServerclienttothatBrokerServer. TheIntegrationServerscertificatefileisstoredonthe machineonwhichtheIntegrationServerresides. Keystore Type ThefiletypeoftheIntegrationServerskeystorefile,which canbeeitherPKCS12orJKS.
133
For this parameter Truststore
Specify ThefullpathtothisIntegrationServerclientstruststorefile. Atruststorefilecontainstrustedrootsforthecertification authoritiesresponsibleforsigningSSLcertificates.Foran SSLconnectiontobemade,avalidtrustedrootfortheSSL certificatestoredinthekeystoremustbeaccessibleinatrust storefile. TheIntegrationServerstruststorefileisstoredonthe machineonwhichtheIntegrationServerresides.Unlikethe keystorefile,whichonlystoresasinglesetofcredentials,a truststorefilecancontainmultipletrustedroots. Notethattruststorefilesarenotpasswordprotected.
Truststore Type Password Encryption 6 ClickSave Changes.
ThefiletypeoftheIntegrationServerstruststorefile,which isJKS. PasswordrequiredtoaccesstheSSLcertificateinthe IntegrationServerskeystorefile. Specifywhetherornottoencrypttheconnectionbetween theIntegrationServerandtheBroker.
Note: IfyouswitchyourIntegrationServerconnectionfromoneBrokertoaBrokerin anotherterritory,youmayneedtosynchronizeyourpublishabledocumenttypes withthenewBroker.SwitchingyourBrokerconnectionisnotrecommendedor supported.Formoreinformation,seeSynchronizingPublishableDocumentTypes inthePublishSubscribeDevelopersGuide. FormoreinformationaboutBroker,andconfiguringSSLforBroker,seethewebMethods BrokerAdministratorsGuide.
Specifying the Keep-Alive Mode for the Broker Connection

AfterconfiguringtheconnectiontotheBroker,youcanspecifythekeepalivemodethat youwantIntegrationServertouse. ThekeepalivemodeindicateswhethertheBrokerchecksfordroppedconnectionsfroma clientandthenexplicitlydisconnectstheclientifithasdroppedtheconnection.By disconnectingtheclient,theBrokermakesanyunacknowledgeddocumentsretrievedby thatclientavailableforredeliverytootherclients. Note: YoucanspecifyakeepalivemodeonlyifIntegrationServerconnectstoa webMethodsBrokerversion6.1orlater.
134
Ifclientstateisnotshared,anundetectedbrokenconnectiondoesnotposeaproblem. TheBrokerwillautomaticallyredeliverunacknowledgedeventstotheclientwhenit reconnects.However,iftheclientstateissharedandaclientlosesitsconnectiontothe Broker,theclientcannotretrievetheunacknowledgeddocumentsafteritreestablishes theconnection.(ThedefaultclientfortheIntegrationServerandalltriggerclientsare sharedstateclients.)ThisisbecausethesameclientIDisusedbyalltheclientsina sharedstateclient.TheBrokercannotdistinguishthereconnectionofoneclientfromthe ordinaryreconnectionsofotherclientswiththesameclientID.Theunacknowledged documentsretrievedbythenowdisconnectedclientwillnotbemadeavailablefor redeliveryuntiltheBrokerreceivesanexplicitdisconnectnotice(generally,whenthe TCP/IPconnectionfinallytimesout).Insomecases,thismightbehourslater. ToavoidasituationinwhichunacknowledgeddocumentsstayontheBrokerforan unacceptableperiodoftime,youcanselectakeepalivemodethatwilldisconnect unresponsiveclientsandmakeunacknowledgeddocumentsavailableforredelivery. Note: FormoreinformationabouttheBrokerkeepalivefeatureandaboutshared stateclients,seethewebMethodsBrokerClientJavaAPIReferenceGuide. Youcanconfigureoneofthefollowingkeepalivemodes: Normal.TheBrokersendsakeepalivemessagetotheIntegrationServerataspecified timeinterval(keepaliveperiod)andexpectsaresponsewithinanotherspecified timeinterval(maxresponsetime).IftheBrokerdoesnotreceivearesponse,itwill retryuptothenumberoftimesspecifiedbytheretrycount.IftheIntegrationServer stilldoesnotrespondtothekeepalivemessage,theBrokerexplicitlydisconnectsthe IntegrationServer.Normalisthedefaultmode. Forexample,bydefault,theBrokersendstheIntegrationServerakeepalivemessage every60seconds.IftheIntegrationServerdoesnotrespondwithin60seconds,the Brokersendsuptothreemorekeepalivemessagesbeforedisconnectingthe IntegrationServer.(Thedefaultretrycountis3.) Listen Only.TheBrokerdisconnectstheIntegrationServerifthereisnoactivityfrom theIntegrationServeroveraspecifiedtimeinterval(keepaliveperiod).Inlistenonly mode,theBrokerdoesnotsendkeepalivemessagestotheIntegrationServerand ignorestheretrycount. Forexample,supposethattheBrokerexpectsactivityfromtheIntegrationServer every60seconds.IfthereisnoactivityfromtheBrokerafter60seconds,theBroker disconnectstheIntegrationServer. Disabled. TheBrokerdisableskeepaliveinteractionwiththisIntegrationServer.The BrokerdoesnotsendkeepalivemessagesanddoesnotdisconnecttheIntegration Serverbecauseofinactivity. Note: TheBrokerdoesnotcommunicatedirectlywithIntegrationServer.TheBroker ClientAPIfacilitatescommunicationbetweenBrokerandIntegrationServer.
135
Setting Server Configuration Parameters for Keep-Alive Mode

Thekeepalivemodeisdeterminedbythecombinationofvaluesforthefollowingsetof serverconfigurationparameters: watt.server.brokerTransport.dur.Specifiesthenumberofsecondsofidletimethatthe BrokerwaitsbeforesendingakeepalivemessagetoIntegrationServer.Thisisthe keepaliveperiod.Thedefaultis60seconds. watt.server.brokerTransport.max.SpecifiesthenumberofsecondsthattheBrokerwaits fortheIntegrationServertorespondtoakeepalivemessage.Thisisthemax responsetime.Thedefaultis60seconds. watt.server.brokerTransport.ret. SpecifiesthenumberoftimestheBrokerresendskeep alivemessagesbeforedisconnectinganunresponsiveIntegrationServer.Thisisthe retrycount.Thedefaultis3. Forinformationaboutsettingakeepalivemodeusingtheseparameters,seethe followingsections.Formoreinformationabouttheseparameters,seeAppendix B, ServerConfigurationParameters.
Normal Mode
Usethesettingsinthefollowingtabletoconfigurenormalkeepalivemode.Thisisthe defaultmode. Set this parameter... watt.server.brokerTransport.dur watt.server.brokerTransport.max watt.server.brokerTransport.ret To... Anyintegergreaterthan0butlessthan2147483647. Thedefaultis60. Anyintegergreaterthan0butlessthanorequalto 2147483647.Thedefaultis60. Anyintegerbetween1and2147483647.Thedefaultis 3.
Listen Only Mode

Usethesettingsinthefollowingtabletoconfigurelistenonlykeepalivemode. Set this parameter... watt.server.brokerTransport.dur watt.server.brokerTransport.max watt.server.brokerTransport.ret To... 2147483647 Anyintegergreaterthanzerobutlessthan2147483647 N/A.Theretrycountisignoredinlistenonlymode.
136
Disabled
Usethesettingsinthefollowingtabletodisablekeepalivemode. Set this parameter... watt.server.brokerTransport.dur watt.server.brokerTransport.max watt.server.brokerTransport.ret To... 2147483647 2147483647 1
137
138
10
Managing Server Security

140 141 142 143 143
Overview of Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up Administrators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up Developers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling and Disabling Well-Known User Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FIPS 140-2 Compliance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
139
10 Managing Server Security
Overview of Security
Tosecureaccesstoyourserverandthedatathatresidesontheserver,youcan: Control who can configure and manage the server. YoucanrestrictaccesstotheIntegration ServerAdministrator. Control who can use webMethods Developer to connect to the server.Youcanspecifywhois authorizedtoview,create,edit,anddeletetheservicesandotherelementsthatreside ontheserver. Secure the transmission of data between IS clients and the server.Youcanconfigureaport forSSLcommunications. Digitally sign documents and verify digital signatures.Youcancodeyourservicestoinvoke abuiltinservice(pub.security.pkcs7:sign)todigitallysignadocument.Similarly,youcan invokeanotherbuiltinservice(pub.security.pkcs7:verify)toensureadocumenthasnot beenalteredsinceitwasdigitallysigned.Inaddition,youcanusePKIprofilesto digitallysignandverifydocuments.Thecorrespondingserviceshereare pub.pki.pkcs7:signandpub.pki.pkcs7:verify.RefertoChapter 14,SecuringYourServer withPKIProfilestolearnmoreabouthowtousePKIprofiles.Refertothe webMethodsIntegrationServerBuiltInServicesReferenceformoreinformationabout thebuiltinservices. Control access to packages, folders, and other elements that reside on the server.Youcan createAccessControlLists(ACLs)thatcontrolaccesstoindividualpackages,folders, andotherelementssuchasspecifications,records,andschemas.Inaddition,youcan restrictwhichservicesareavailableforexecutionfromspecificports. Specify how you want the server to authenticate clients.Thisallowsyoutoauthenticatea clientbasedonclientcertificatesorusername/passwordauthentication.Inaddition, theIntegrationServeralsosupportsIntegratedWindowsauthenticationwhenthe serveractsasaWebclienttoaccessinformationfromaserver.(MicrosoftInternet InformationServerisanexampleofaserverthatsupportstheMicrosoftWindows NTbuiltinauthenticationmechanism.) Use different certificates for different connections. Thisallowsyoutospecifydifferent certificates(andassociatedprivatekeys)dependingonthehostwithwhichtheserver iscommunicating. Isolate your webMethods Integration Server behind an inner firewall.Youcanusethereverse invokefeaturetoplaceaReverseHTTPGatewayServertointerceptrequestsfrom externalclientsbeforepassingtherequeststoyourinternalserver.SeeChapter 15, SettingUpaReverseHTTPGatewayformoreinformation.
140
Setting Up Administrators
UsetheIntegrationServerAdministratortoconfigureandmanagetheserver.Beforethe serverallowsaccesstotheIntegrationServerAdministrator,itensurestheuserhas administratorprivileges. AuserhasadministratorprivilegesifheorshebelongstotheAdministratorsgrouporto anyothergroupaddedtotheAllowListoftheAdministratorsACL.Todetermineifa userhasadministratorprivileges,theserverauthenticatestheusertoobtainhisorher username.(Forinformationabouthowtheserverdeterminestheusername,see Chapter 13,AuthenticatingClients.)Afterdeterminingtheusername,theserver determinesiftheuserbelongstoagroupthatisallowedanddoesnotbelongtoany groupthatisdeniedaccessbytheAdministratorsACL.Ifso,theserverallowsaccessto theIntegrationServerAdministrator. Tograntadministratorprivilegestoauser,youmustassignthatusertothe AdministratorsgrouportoagroupyouhaveaddedtotheAllowlistofthe AdministratorsACL.Inaddition,youmustmakesuretheuserisnotamemberofa groupthatisdeniedaccessbytheAdministratorsACL. Important! Theusertowhomyouwanttograntadministrativeprivilegesmustalready haveauseraccountontheIntegrationServer.Iftheuserdoesnotalreadyhaveauser account,createonebeforeyouperformthefollowingsteps. To grant administrative privileges to a user 1 2 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecurity menuoftheNavigationpanel,clickUser Management. UnderLocal User Management,theGroupsareaofthescreen(ontheright)containstwo lists.Users in this Group isalistofuserscurrentlyintheselectedgroup.Remaining Users isalistofusersnotcurrentlyintheselectedgroup. 3 4 IntheGroupsareaofthescreen,intheSelect grouplist,selectAdministrators. IntheRemaining Userslist,select(highlight)theuseroruserstowhomyouwantto grantadministratorprivileges. Toselectadditionaluserswithoutdeselectingcurrentlyselectedusers,pressthe CTRLkeywhileyouclickontheusersyouwanttoselect.Todeselectauser,pressthe CTRLkeywhileyouclickthecurrentlyselectedentry. 5 6 Afteryouhaveselectedalltheusersyouwanttoaddtothegroup,click Theservermovestheselecteduserstothe Users in this Group list. Click Save Changes. Note: Alternatively,youcancreateanewgroupsuchasLocalAdministrators,addthat grouptotheAdministratorsACLsallowlist,andaddtheusertothatgroup. .
141
Setting Up Developers
AdevelopercanusewebMethodsDevelopertoview,create,modify,anddelete packages,folders,services,andotherelementsthatresideontheserver.Beforetheserver allowsaconnectionfromtheDeveloper,itensuresthattheuserhasdeveloperprivileges. AuserhasdeveloperprivilegesifheorshebelongstotheDevelopersgrouportoany othergroupaddedtotheAllowListoftheDevelopersACL.Todetermineifauserhas developerprivileges,theserverauthenticatestheusertoobtaintheirusername.(For informationabouthowtheserverdeterminestheusername,seeChapter 13, AuthenticatingClients.)Afterdeterminingtheusername,theserverdeterminesifthe userbelongstoagroupthatisallowedanddoesnotbelongtoanygroupthatisdenied accessbytheDevelopersACL.Ifso,theserverallowstheconnectionbetweenthe Developerandtheservertobeestablished. Tograntdeveloperprivilegestoauser,youmustassignthatusertotheDevelopers grouportoagroupyouhaveaddedtotheAllowlistoftheDevelopersACL.Inaddition, youmustmakesuretheuserisnotamemberofagroupthatisdeniedaccessbythe DeveloperACL. Important! List,Read,andWriteACLsareamechanismforprotectingagainst accidentaltamperingordestructionofelements.Adevelopermakingadeliberate attemptcanbypassthismechanism.DonotrelyonACLsforprotectioninahostile environment. Important! Theusertowhomyouwanttograntdeveloperprivilegesmustalready haveauseraccountontheIntegrationServer.Iftheuserdoesnotalreadyhaveauser account,createonefortheuserbeforeyouperformthefollowingsteps. To grant developer privileges to a user 1 2 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecurity menuoftheNavigationpanel,clickUser Management. UnderLocal User Management,intheGroupsareaofthescreen(ontheright)contains twolists.Users in this Group isalistofuserscurrentlyintheselectedgroup.Remaining Users isalistofusersnotcurrentlyintheselectedgroup. 3 4 IntheGroupsareaofthescreen,intheSelect grouplist,selectDevelopers. IntheRemaining Userslist,select(highlight)theuseroruserstowhomyouwantto grantdeveloperprivileges. Toselectadditionaluserswithoutdeselectingcurrentlyselectedusers,pressthe CTRLkeywhileyouclickontheusersyouwanttoselect.Todeselectauser,pressthe CTRLkeywhileyouclickthecurrentlyselectedentry.
142
5 6
Afteryouhaveselectedalltheusersyouwanttoaddtothegroup,click Theservermovestheselecteduserstothe Users Currently in this Group list. Click Save Changes.
Note: Alternatively,youcancreateanewgroupsuchasLocalDevelopers,addthat grouptotheDevelopersACLsallowlist,andaddtheusertothatgroup.
Enabling and Disabling Well-Known User Accounts

WhenyouarereadytodeploytheIntegrationServer,itmaybeadvisable,forsecurity reasons,todisablethewellknownbuiltinuseraccountssuchasAdministrator, Developer,andReplicator.Forexample,youmightcreateanewadministratoraccount SmithAdmin,andthendisableAdministrator. SeeDisablingandEnablingUsersonpage 52formoreinformationaboutdisabling users.
FIPS 140-2 Compliance

webMethodsIntegrationServerVersion 7.1embedstheEntrustAuthoritySecurity ToolkitforJava7.2,whichhasobtainedFIPS1402validation.FIPS(FederalInformation ProcessingStandards)providesstandardsforinformationprocessingforusewithinthe Federalgovernment.ThepolicyforVersion7.2isavailableatthefollowing: http://csrc.nist.gov/groups/STM/cmvp/documents/1401/140sp/140sp802.pdf ManygovernmentandfinancialorganizationsrequirethattheirsoftwarebeFIPS1402 compliant,whichfollowsthecurrentstandardsandguidelinesforcryptographic informationprocessing. Note: IntegrationServeritselfisnotconsideredtobeFIPS140certified. RunningIntegrationServerinFIPS1402compliantmodeensuresthatitonlyusesFIPS compliantalgorithmsintheFIPScompliantmodes.YoucanenableFIPSmodebysetting thefollowingextendedsettingontheIntegrationServer:
watt.security.fips.mode=true
RefertoAppendix B,ServerConfigurationParametersonpage 407foradetailed descriptionofthisserverconfigurationparameter.Also,refertoSwitchingfromthe EmbeddedDatabasetoanExternalRDBMSonpage 79forinstructionsonviewingand updatingextendedsettingsfortheIntegrationServer. InadditiontorunningtheserverinFIPScompliantmode,youmustfollowtheother instructionsintheEntrustCryptographicModuleSecurityPolicy.Theinstructions includeimplementingsafeguardssuchasnotallowingmultipleuserstoaccessthe computerandensuringthatthecomputerisphysicallyprotected.Inparticular,see section5.4ofthatdocument(OperationalEnvironment).Dependingonyour
143
organizationspolicies,youmightalsoberequiredtousethesamehardware,operating system,andJDKaswasusedintheEntrustapproval. Note: FIPSmodeencryptionisonlyapplicabletoHTTPSorFTPScommunicationsand S/MIMEencryption/signing.CommunicationbetweenIntegrationServerandthe BrokerdoesnotuseFIPScompliantalgorithms.
144
11
Securing Communications with the Server

146 148 149 151 151 153 156
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Checklist for Using SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Items You Need Before Configuring SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Obtaining the Certificate of the CA that Signed an Internet Resources Certificate . . . . . . . . . . . Configuring the Server to Use SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring the Server to Present Multiple Client Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling Server SSL Security Level by Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
145
11 Securing Communications with the Server
Overview
AnadministratorcanconfiguretheIntegrationServertouseSecureSocketsLayer(SSL) toprovidesecurecommunicationswiththeserver.UseSSLtoensurethatdatais transmittedprivatelyandthatthecontentofthedataisnotalteredduringtransit.
Background About SSL

InanSSLtransaction,thereisanSSLclientandanSSLserver.TheSSLclientinitiatesan SSLtransaction.AtthebeginningofanSSLtransaction,theclientandserverperform whatiscalledanSSLhandshake: 1 Theserversendsitsdigitalcertificatetotheclient.Theclientusesthiscertificateto authenticatetheserver,whichassurestheclientthatitiscommunicatingwiththe organizationthatthecertificateidentifies. Optionally,theservercanrequestaclientcertificatefromtheclient.Theservercan usetheclientcertificatetoauthenticatetheclient. Theclientandtheservernegotiatehowtheywillsecurelytransmitdata.
2 3
SSL and the Integration Server

Dependingonthesituation,theIntegrationServercanbeeitheraclientoraserverinan SSLtransaction.
When the Integration Server Is an SSL Server

WhenanISclientcommunicatesviaHTTPSorFTPSwiththeIntegrationServer,theIS clientistheSSLclientandtheIntegrationServeristheSSLserver. Ifitisconfiguredtodoso,theIntegrationServerwillasktheclientforacertificate.See Chapter 13,AuthenticatingClientsformoreinformationabouthowtheIntegration Serverauthenticatesclients.
SSL Client SSL Server
Client Application HTTPS or FTPS
webMethods Integration Servers
146
When the Integration Server Is an SSL Client

WhenaserviceontheIntegrationServersubmitsanHTTPSorFTPSrequesttoanother resourceontheInternet,theIntegrationServeristheSSLclientandthetargetsystemto whichitiscommunicatingistheSSLserver.
SSL Client SSL Server
webMethods Integration Servers
Internet Resource HTTPS or FTPS
WhentheserveractsasanSSLclient,aspartoftheSSLhandshakeitreceivesthedigital certificateoftheInternetResourcetowhichitisconnecting.Thedigitalcertificateis usuallypartofadigitalcertificatechain.Thechaincontainsthecertificatesofoneormore certificateauthorities(CAs)andthedigitalcertificateoftheInternetResource.

CA certificate CA certificate Internet Resource digital certificate
Attimes,oneormoreCAcertificatesinthechainmightbeexpired.WhenaWebbrowser connectstotheInternetresource,itmightaccepttheconnectionevenifitreceivesan expiredCAcertificate.TheWebbrowseracceptstheconnectionifithasonfileavalid certificatefortheCAwhosecertificateisexpired.Incontrast,theIntegrationServerdoes notacceptaconnectionwhenoneoftheCAcertificatesinthechainisexpiredunlessyou specificallyconfiguretheIntegrationServertodoso. IfyouwanttheIntegrationServertoacceptaconnectionwhenoneormoreoftheCA certificatesinthechainareexpired,youmustupdatethe watt.security.ssl.ignoreExpiredChainspropertyintheserverconfigurationfile (server.cnf)totrue.ThissettingwillcausetheservertoignoreexpiredCAcertificatesin thechain.Tochangethissetting,usetheSettings > ExtendedscreenoftheIntegration ServerAdministrator,asdescribedinSwitchingfromtheEmbeddedDatabasetoan ExternalRDBMSonpage 79.Remembertorestarttheserverafterchangingthesetting.
147
Presenting Multiple Client Certificates

Note: Itislesssecuretoignoretheexpiredcertificatesthantodenytheconnection duetoexpiredcertificates. TheIntegrationServercanpresentasingleclientcertificatetoallserversoritcanpresent differentclientcertificatestodifferentSSLservers.Inaddition,theIntegrationServercan presentcertificatesprovidedforthispurposebyotherorganizations.(Some organizationsprefertoprovidecertificatessignedbytheirownCAsforclientstouse, ratherthanaccepttheclientscertificate.)YoucontrolwhichcertificatetheIntegration ServerpresentstoanSSLserverbyusingremoteserveraliasesorspecialpublicservices. SeeConfiguringtheServertoPresentMultipleClientCertificatesonpage 153formore information.
Checklist for Using SSL

Task UsethewebMethodsCertificateToolkittocreatea privatekeyandacertificatesigningrequest(CSR) foradigitalcertificateandsendittoacertificate authority. Notes RefertoItemsYouNeed BeforeConfiguringPorts toRequestClient Certificatesonpage 186 andtothewebMethods CertificateToolkitUsers Guide. RefertothewebMethods CertificateToolkitUsers Guide. RefertothewebMethods CertificateToolkitUsers Guide.
Waitforyoursignedcertificate.Periodicallycheck thestatusofyourrequest. Obtainyourdigitalcertificateandthecertificateof thecertificateauthoritythatsignedyourdigital certificate.UsethewebMethodsCertificateToolkit tomakethecertificatesavailabletotheIntegration ServerandconvertthemtoDERformatif necessary. IftheIntegrationServerwillactasanSSLclient, obtainthedigitalcertificatesofthecertificate authoritiesthatsignedthecertificatesforthe Internetresourcesthatyouwillconnectto.Place eachcertificateinaseparatefile.Placethefilesin thedirectoryyouusetostoredigitalcertificatesof certificateauthorities.
RefertoItemsYouNeed BeforeConfiguringPorts toRequestClient Certificatesonpage 186 andObtainingthe CertificateoftheCAthat SignedanInternet ResourcesCertificateon page 151.
148
Task ConfiguretheIntegrationServertouseSSL.
Notes RefertoConfiguringthe ServertoUseSSLon page 151. RefertoSettingUp AliasesforRemote IntegrationServerson page 68.
AddanHTTPSorFTPSportifnonearedefined. Ifyouwanttoallowonlysecureconnectionstothe server,ensurethattheprimaryportusesanHTTPS orFTPSportanddeleteallothernonHTTPSor nonFTPSports.AddasmanyadditionalHTTPSor FTPSportsasyouwant. Ifyouwanttoauthenticateusingclientcertificates butwillallowclientswithoutcertificatesto authenticateusingpasswords,configuretheserver torequestclientcertificates. Ifyouwanttoauthenticateusingclientcertificates andwillnotallowclientstoauthenticateusing passwords,configuretheservertorequireclient certificates.
RefertoChapter 13, AuthenticatingClients.
Items You Need Before Configuring SSL

BeforetheIntegrationServercanactasanSSLserverorSSLclient,youmustobtainitems thatarerequiredforanSSLtransaction.Toobtainmostoftheseitems,youcanusethe webMethodsCertificateToolkit.ForinstructionsonusingthewebMethodsCertificate Toolkit,seethewebMethodsCertificateToolkitUsersGuideonwebMethodsAdvantage Websiteathttp://advantage.webmethods.com. Private/Public Key. TheSSLserverandSSLclientusepublickeyencryption(alsoknown asasymmetricencryption)duringtheSSLhandshake.Thistypeofencryption requiresakeypairthatismadeupofapublickeyandaprivatekey.Thedatathatis encryptedwithoneofthekeyscanonlybedecryptedusingtheotherkeyinthepair. YouusethewebMethodsCertificateToolkittocreatetheprivate/publickeypair.You placetheprivatekeyofthekeypairinafile.Thetoolkitusestheprivatekeytocreate thepublickeythenplacesthepublickeyinthecertificatesigningrequest.Thekey thenbecomespartofthedigitalcertificatefortheIntegrationServer. ThepartywithwhichtheIntegrationServeriscommunicatingobtainsthepublickey fromtheIntegrationServerscertificate.Tocommunicatesecurely,theotherpartycan encryptinformationwiththepublickeybeforesendingittotheIntegrationServer, whichdecryptstheinformationwithitsprivatekey. RefertothewebMethodsCertificateToolkitUsersGuideforinstructionsoncreatingthe privatekey.
149
Digital Certificate for the Integration Server. Adigitalcertificateatteststotheidentityofthe IntegrationServer.YoucanusethewebMethodsCertificateToolkittocreatea CertificateSigningRequest(CSR)foradigitalcertificateandtomakethecertificate availableonyourserver. AftercreatingtheCSR,thewebMethodsCertificateToolkittakesyoutotheVerisign websitesothatyoucansendyourrequesttothem.RequestthecertificateinDER format.IfyoureceiveacertificateinPEMformat(oranyformatotherthanDER),use thewebMethodsCertificateToolkittoconvertittoDERformat. WhentheIntegrationServeractsasanSSLserver,itusesthiscertificateintheSSL handshaketoidentifyitselftotheclient.WhentheIntegrationServeractsasanSSL clientandtheSSLserverrequestsaclientcertificate,theIntegrationServerpresents thiscertificateasitsclientcertificate. TheIntegrationServercanpresentitsownclientcertificateorcertificatesprovidedby otherorganizations.Forexample,someorganizationsprefertoprovidecertificates signedbytheirownCAsforclientstouse,ratherthanaccepttheclientscertificate. YoucansetupthewebMethodsIntegrationServertopresentclientcertificatesfrom multipleorganizations.Thisinvolvesobtainingthecertificatesandsettingthemup onyourserver,thenusingremotealiasesorspecialpublicservicestocontrolwhich certificateisbeingpresented. RefertothewebMethodsCertificateToolkitUsersGuideforinstructionsonobtaininga certificatefortheIntegrationServer.RefertoConfiguringtheServertoPresent MultipleClientCertificatesonpage 153formoreinformationaboutsending differentcertificatestodifferentSSLservers. Certificate of the CA that signed the webMethods Integration Servers Server certificate.The signingCAscertificateatteststotheidentityoftheCAthatsignedthedigital certificatefortheIntegrationServer.TheCAshouldsendthiscertificatetoyouwhen itsendsyouthedigitalcertificatefortheIntegrationServer.IfitisnotinDERformat, youcanusethewebMethodsCertificateToolkittoconvertittoDERformat. WhentheIntegrationServeractsasanSSLclientandtheSSLserverrequestsaclient certificate,theIntegrationServerpresentsthiscertificatealongwithitsclient certificate. Ifthecertificateauthoritydoesnotsendyouitscertificate,refertothewebMethods CertificateToolkitUsersGuideforinstructionsonobtainingit. Certificate of the CA that signed an Internet resources certificate. IfyourIntegrationServer willrunservicesthatsubmitHTTPSorFTPSrequeststootherresourcesonthe Internet,theIntegrationServerwillbeactingasaclientandwillreceivecertificates fromtheseresources.Inorderforthesetransactionstowork,yourIntegrationServer musthaveonfilecopiesoftheCAcertificatesoftheInternetresources.Forexample, ifyourIntegrationServerrunsaservicethatrequestsservicesfromMolly Manufacturing,yourIntegrationServermusthaveonfileacopyofthecertificateof theCAthatsignedMollyManufacturingscertificate.RefertoObtainingthe CertificateoftheCAthatSignedanInternetResourcesCertificatebelow.
150
Obtaining the Certificate of the CA that Signed an Internet Resources Certificate

YoumaybeabletoobtainthecertificateoftheCAthatsignedthecertificateofanInternet Resourceyouwanttousebyimportingiffromyourbrowser.Browserstypicallycontain thedigitalcertificatesofmanycertificateauthorities.Themethodyouusetoobtainthe certificatedependsonyourbrowser.Anothermethodistocopythecertificatefromthe CAswebsite. AfteryouobtaintheCAcertificate,youmustcopyittotheCAcertificatedirectory.The locationofthisdirectoryisspecifiedunderTrusted CertificatesontheSecurity> Certificatesscreen. TheIntegrationServerreadsthisdirectoryandloadsthecertificatesintocacheatstartup. IfyouaddaCAcertificatetothedirectoryafterstartupandwanttheIntegrationServer toloaditintocachebeforethenextstartup,clickRefresh Trusted CA Certificates Cacheon theSecurity>Certificatesscreen.
Configuring the Server to Use SSL

BeforeyouconfigureyourIntegrationServertouseSSL,makesureyouhavereadItems YouNeedBeforeConfiguringPortstoRequestClientCertificatesonpage 186. ThefollowingproceduredescribeshowtosetuptheIntegrationServertouseSSLfor securetransmissionofdata.Ifyouwanttosetuptheservertorequestorrequireclient certificatesforauthenticatingclients,seeChapter 13,AuthenticatingClients. To configure the server to use SSL for secure communications 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecurity menuoftheNavigationpanel,clickCertificates. ClickEdit Certificates Settings. SettheOutbound SSL Certificateparametersasfollows: For this parameter Server's Signed Certificate Signing CA's Certificate Server's Private Key Specify PathandfilenameofthefilethatcontainstheIntegration Serversdigitalcertificate. Pathandfilenameofthefilethatcontainsthecertificatefor thecertificateauthoritythatsignedtheIntegrationServers digitalcertificate. Pathandfilenameofthefilethatcontainstheprivatekeyof theprivate/publickeypairassociatedwiththeIntegration Serversdigitalcertificate.
151
Note: TheIntegrationServerusesthecertificateinformationonthisscreenforSSL communicationsthroughaportunlessyouhavespecifieddifferentcertificate informationforthatport.SeeSettingUpAliasesforRemoteIntegrationServerson page 68formoreinformationaboutconfiguringportsandConfiguringtheServerto PresentMultipleClientCertificatesonpage 153. 5 IntheTrusted Certificatesareaofthescreen,intheCA Certificate Directory field,typethe nameofthedirectory(relativetotheserverhome)thatcontainsthedigitalcertificates ofcertificateauthoritiestrustedbythisserver,forexampleconfig\cas. Note: Mostofthetimeyouwillwanttospecifyatrustedcertificatesdirectory; however,theremaybetimeswhenyouwanttoleaveitblank.Forexample,you mightwanttotrustallcertificateauthoritiesonoutboundrequestsandtrustspecific CAsondifferentportsforincomingrequests.Foroutboundrequests(acertificatethe serverreceivesfromaserverthatitsubmitsarequestto),ifyouleavethisfieldblank orspecifyadirectorythatdoesnotcontaincertificatesforCAs,bydefault,theserver trustsallcertificateauthorities.Thepropertythatcontrolsthisbehavior (watt.security.cert.wmChainVerifier.trustByDefault)issettoTruebydefault.If thispropertyissettoFalseandnodirectoryoranemptydirectoryisspecified,the serverwilltrustnocertificatesforoutboundrequests. Forinboundrequests,youcanspecifyatrustedcertificatesdirectoryattheserver level(ontheSecurityCertificatesscreen)orattheportlevel(ontheEditHTTPSPort ConfigurationscreenortheEditFTPSPortConfigurationscreen).Ifyouomita trustedauthoritiesdirectory(orspecifyadirectorythatdoesnotcontainCA certificates)fromboththeserverlevelandtheportlevel,theserverwilltrustno certificateauthorities.Ifyouspecifyatrustedauthoritiesdirectoryattheserverlevel andattheportlevel,theserverusesthedirectoryspecifiedattheportlevelfor determiningtrustonconnectionsbeingmadetothatport.Ifyouspecifyatrusted authoritiesdirectoryatjusttheportlevel,theserverusestheportlevelsettingfor requestsbeingmadetotheport. ForS/MIMEsignaturetrustvalidation,ifyouleavethisfieldblankorspecifya directorythatdoesnotcontainthecertificatesoftrustedCAs,bydefaulttheserver trustsallsignaturesonS/MIMEmessages.However,if watt.security.cert.wmChainVerifier.trustByDefaultissettoFalseandnodirectory oranemptydirectoryisspecified,theserverwilltrustnosignaturesonS/MIME messages. 6 7 ClickSave Changes. AddanHTTPSorFTPSportifonedoesnotalreadyexist.Formoreinformationabout creatingports,seeChapter 7,ConfiguringPorts.SpecifyHTTPSorFTPSforthe typeofport.Makesurenootherapplicationsarelisteningontheportyouwantto use. ForHTTPSprotocol,thestandardportis443;forFTPSitis990.
152
Note: IfyourIntegrationServerrunsonaUNIXsystem,usingaportnumberbelow 1024requiresthattheserverrunasroot.Forsecurityreasons,Software AG discouragesthispractice.Instead,runyourIntegrationServerusinganunprivileged userIDonahighnumberport(forexample1024orabove)andusetheport remappingcapabilitiespresentinmostfirewallstomoverequeststothehigher numberedports. Testwhetheryourserverislisteningtohttpsrequestsontheportyouspecified.Bring upyourbrowserandtypeinhttps://localhost:portorftp://localhost:port.Ifthe portisworkingproperly,youwillseethelogonscreenfortheIntegrationServer Administrator. IftheIntegrationServerAdministratordoesnotdisplay,checkthefollowing: IfyouusedthewebMethodsCertificateToolkittocreatethiscertificate,make surethekeyyouspecifiedontheConvert and Save Certificates for use with webMethods SoftwarescreenisthesameasthekeyyousentwithyourCSR.Ifthe keysdonotmatchandthecorrectoneistheoneyousentwiththeCSR,thengoto theConvert and Save Certificates for use with webMethods Softwarescreenandperform theconversionagain,thistimespecifyingthecorrectkey.Ifthekeyyousentwith yourCSRisnotthecorrectone,thenyoumustresubmittheCSR,thistime specifyingthecorrectkey. Checktoseeifaservicerunningonthemachineislisteningtothesameport. 8 IfyouwanttheservertoignoreexpiredCAcertificatesthatitreceivesfroman Internetresource(i.e.,aWebserver,anotherIntegrationServer),updatethe watt.security.ssl.ignoreExpiredChainspropertytobetrue.Forinformationabout thissetting,seeWhentheIntegrationServerIsanSSLClientonpage 147. IfyouwanttheIntegrationServertocacheSSLsessioninformation(e.g.,client certificates),ensurethewatt.security.ssl.cacheClientSessionspropertyissetto true.IftheSSLsessioninformationfrequentlychangesforclients(e.g.,changesto clientcertificates),setthispropertytofalse.Formoreinformationontheproperty, seeAppendix B,ServerConfigurationParameters. Note: Tochangeserverconfigurationsettings,usetheSettings > Extendedscreenofthe IntegrationServerAdministrator,asdescribedinSwitchingfromtheEmbedded DatabasetoanExternalRDBMSonpage 79.Remembertorestarttheserverafter changingthesettings.
Configuring the Server to Present Multiple Client Certificates

TheIntegrationServercanpresentasingleclientcertificatetoallSSLserversit communicateswithoritcanpresentdifferentclientcertificatestodifferentSSLservers. TheclientcertificatesthattheIntegrationServerpresentscanbeitsownorcertificates providedbyotherorganizations.Someorganizationsprefertoprovidecertificatessigned bytheirownCAsforclientstouse,ratherthanaccepttheclientscertificate.Forexample,
153
supposecompanyAwantstoexchangeinformationwithcompanyB,butCompanyB doesnottrustclientcertificatesunlesstheyaresignedbytheirownCA.Therefore,in ordertodobusinesswithB,AmustobtainacertificatefromcompanyBandpresentit whenconnectingtocompanyAsserver. Inthefollowingdiagram,CompanyBandCompanyCrequirethatcertificatessignedby theirCAbepresentedbytheclient.CompanyDacceptsCompanyAsclientcertificate.

Server A acting as a client
As certificate
Integration Server
Server B acting as an SSL server Requires own certificate
Integration Server
Bs certificate
Integration Server
Server C acting as an SSL server Requires own certificate
Cs certificate
Integration Server
Server D acting as an SSL server Accepts clients certificate
Checklist for Presenting Multiple Client Certificates

Task Obtainacopyofthe certificateyouwanttouse Notes Youcanuseanexistingone,createone,orobtain onefromtheSSLserverwithwhichyouwantto communicate.SeeObtainingCertificatesbelow forinstructions. Althoughnotrequired,usingaremoteserveralias isaconvenientwayofdirectingparticular certificatestoparticularSSLservers.SeeSetting UpaRemoteServerAliasbelowforinstructions. Howyoucodeyourflowsdependsonwhetheror notyouhavedefinedaremoteserveraliasforthe remoteserver.SeeCodingYourFlowServices belowformoreinformation.
Setuparemotealias
Codeyourflows
154
Obtaining Certificates
MakethecertificateyouwanttouseavailabletoyourIntegrationServer.Ifyoudonot alreadyhavethecertificateyouwanttouse,youcancreateitusingthewebMethods CertificateToolkit.RefertothewebMethodsCertificateToolkitUsersGuideforinstructions onusingthetoolkit.IfyouaregoingtouseacertificateprovidedbytheSSLServerwith whichyouwanttocommunicate,obtainthecertificatefromthatorganization. PlacethecertificateinalocationthatiseasilyaccessibletotheIntegrationServer.Agood placeistheserversconfigdirectory.Forexample,youcouldputtheclientcertificateto usewithCompanyBinwebMethods_directory\config\certs\companyB.
Setting Up a Remote Server Alias

Usingaremoteserverisaconvenientwayofpresentingdifferentcertificatestodifferent SSLservers.Communicationthroughthealiasisoptimized,makingtransactionswiththe remoteserverfaster.Inaddition,usinganaliasismoreconvenientbecauseitsavesyou fromspecifyingconnectioninformationeachtimeyoucommunicatewiththeremote server. AssignaremoteserveraliastotheSSLservertowhichyouwanttopresentaspecial certificate.SeetheinstructionsinSettingUpAliasesforRemoteIntegrationServerson page 68.Itisthealiasthatcontrolswhichcertificateispresentedtotheremoteserver.If youdonotusethealias,youmustcontrolwhichclientcertificatetheIntegrationServer presentsbyusingbuiltinservices.Theseservices,pub.security:setKeyAndChainor pub.security:setKeyAndChainFromBytes(aswellaspub.security:clearKeyAndChainor pub.security:clearKeyAndChainFromBytes),aredescribedbelowandinmoredetailinthe webMethodsIntegrationServerBuiltInServicesReference.
Coding Your Flow Services

Howyoucodeyourflowservicesdependsonwhetherornotyouhavedefinedaremote serveraliasfortheSSLserveryouwanttocommunicatewith.Ifyouareusingaremote serveralias,thealiascontrolswhichcertificateispresented.Witharemoteserveralias defined,youcanusethepub.remote:invokeservicesinyourflowservicestorunserviceson theremoteserver. Ifyouhavenotdefinedaremoteserveralias,youmustcodeyourflowservicestohandle switchingfromonecertificatetoanotherusingspecialpublicservicesprovidedby webMethodsIntegrationServer.Thepub.security:setKeyAndChainor pub.security:setKeyAndChainFromBytesservicetellsyourIntegrationServerwhichclient certificatetopresent.The pub.security:clearKeyAndChainor pub.security:clearKeyAndChainFromBytesservicetellsyourIntegrationServertorevertbackto thedefaultcertificate.AlltheseservicesaredocumentedinthewebMethodsIntegration ServerBuiltInServicesReference.
155
Controlling Server SSL Security Level by Port

YoucanconfigureyourIntegrationServertopresentdifferentservercertificateswith differentports.OnereasontodothisissothatdifferentportscanprovidedifferentSSL securitylevels.Youdeterminethesecuritylevelofacertificateduringthecertificate signingprocess.Youtellthecertificateauthoritywhichclassofcertificateyouneedandit createsacertificatewiththoseattributes.Later,whenyouconfigureyourports,you specifythecertificatethathasthesecuritylevelyouwanttoassociatewiththatport.See SettingUpAliasesforRemoteIntegrationServersonpage 68forinstructionson configuringyourports.
156
12
Controlling Access to Resources

158 158 159 164 167 168
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling Access to Resources by Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Restricting IP Addresses that Can Connect to a Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Restricting the Services Available from a Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling the Use of Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling Access to Resources with ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
157
12 Controlling Access to Resources
Overview
Whentheserverreceivesaclientsrequesttoaccessaservice,theserverperformsa numberofcheckstomakesuretheclientisallowedtoaccesstheservice.Theserver performsthefollowingchecks,intheordershownbelow.Theclientmustpassallchecks toaccesstheservice: 1 Does the port allow connections from this clients IP address?Theserverchecksallow/deny listsofIPaddressesthatareallowedtoconnecttotheserverthroughthisport.Ifthe IPaddressisallowed,theserverperformsthenexttest.Otherwisetheserverrejects therequest. Is the requested service available from this port? Theserverchecksallow/denylistsof servicesthattheservermakesavailableforexecutionfromthisport.Iftheserviceis availablefromthisport,theserverperformsthenexttest.Otherwisetheserverrejects therequest.Theserverperformsthistestforrequeststoexecuteservices.Itdoesnot performthistestforrequestsforlist,read,orwriteaccesstoservices. Is the requesting user allowed to access this service?Theservercheckstheusername associatedwiththerequestagainsttheappropriateaccesscontrollist(ACL) associatedwiththeservice. TheservercheckstheusernameagainsttheList,Read,Write,orExecuteACL associatedwiththeservice.IftheuserbelongstoagroupthatislistedintheACL,the serveracceptstherequest.Otherwisetheserverrejectstherequest. YoucanconfigurethesesettingsusingtheIntegrationServerAdministrator. TolimitIPaddressesthatconnecttoaportseeRestrictingIPAddressesthatCan ConnecttoaPortonpage 159below. TolimittheservicesavailablefromaportseeRestrictingtheServicesAvailablefrom aPortonpage 164. Touseaccesscontrolliststocontrolwhichuserscanaccessanelementsee ControllingAccesstoResourceswithACLsonpage 168.
Controlling Access to Resources by Port

Bydefault,theIntegrationServerprovidesanHTTPportat5555thatallowsallhosts (identifiedbytheirIPaddresses)toconnecttoitandallowsaccesstoallservicesthrough thatport(unlessprohibitedbyanACL).AlthoughthisportisidealforinitialIntegration Serverinstallationandconfiguration,aswellasmanydevelopmentenvironments,for deployment,youshouldreplacethisportwithportsthatallowconnectionsfromonly specifiedIPaddresses(thoseofyourpartnersandusers)andmakeonlyspecified servicesavailable. Note: Bydefault,theIntegrationServeralsoprovidesadiagnosticportat9999that allowsallhoststoconnecttotheserver.However,userscanaccessonlytheservices definedwiththeAdministratorsACL.
158
Thissectiondescribescontrollingaccesstoresourcesattheportlevel.Tocontrolaccess usingAccessControlLists,seeControllingAccesstoResourceswithACLson page 168.
Restricting IP Addresses that Can Connect to a Port

Foranygivenport,youcanspecifyIPaccessoneoftwoways: Deny by Default.Setuptheporttodenyrequestsfromallhostsexceptforonesyou explicitlyallow.Usethisapproachifyouwanttodenymosthostsandallowafew. Allow by Default.Setuptheporttoallowrequestsfromallhostsexceptforonesyou explicitlydeny.Usethisapproachifyouwanttoallowmosthostsanddenyafew. Youcanspecifythesesettingsglobally(forallports)orindividually(foroneport). Thefollowingtableshowswheretofindinformationaboutassigningthedifferenttypes ofIPaccess: Type of access Controlling IP Access Globally DenybyDefault AllowbyDefault Controlling IP Access of Individual Ports DenybyDefault AllowbyDefault AllowInboundRequestsfromSpecifiedHosts (DenyAllOthers)onpage 162 DenyInboundRequestsfromSpecifiedHosts (AllowAllOthers)onpage 163 AllowInboundConnectionsfromSpecified Hosts(DenyallOthers)onpage 160 DenyInboundConnectionsfromSpecified Hosts(AllowAllOthers)onpage 161 Where to look for instructions
Controlling IP Access to All Ports (Globally)

ThissectiondescribeshowtospecifytheglobalIPaccesssettingforports.Theserver usesthissettingtodetermineIPaccessforportsthatdonothaveacustomIPaccess setting.ThedefaultglobalsettingisAllowbyDefault. Whenyoucreateaport,youcancustomizeIPaccessforit,oryoucanspecifythatituse theglobalIPaccesssettingfortheserver.IfyouusetheglobalIPaccesssettingandlater changeit,theserverusesthenewglobalsettingfortheport.Forexample,asshipped,the serverusesAllowbyDefaultastheglobalIPaccesssetting(withnohostsexplicitly denied).Ifyoucreateanewport6666anddonotcustomizeIPaccessforit,theserver usesAllowbyDefaultforport6666.IfyoulaterchangetheglobalIPaccesstoDenyby Default,theserverthenusesDenybyDefaultforport6666.IfyoulatercustomizeIP
159
accesstoport6666,subsequentchangestotheglobalsettingwillhavenoeffectonport 6666. TocustomizeIPaccessforindividualports,seeControllingIPAccesstoIndividual Portsonpage 162.
Allow Inbound Connections from Specified Hosts (Deny all Others)

ThefollowingproceduredescribeshowtochangetheglobalIPaccesssettingtoDenyby Defaultandspecifysomehoststoallow. Withthissettingineffect,theserverdeniesmosthostsandallowssome. Important! BeforeyouswitchyourglobalsettingtoDenybyDefault,makesureyou haveatleastoneportthatdoesnotrelyontheglobalsettingandallowsatleastone host.Ifyouinadvertentlylockallhostsoutoftheserver,youcancorrecttheproblem bymanuallyupdatingtheappropriateconfigurationfile,asshownbelow. Before updating these configuration files, be sure to shut down the Integration Server. Toresettheglobalsetting,updatethewatt.server.hostAllowparameterinthe server.cnffile.Forexample:
watt.server.hostAllow=132.906.19.22
Toresetanindividualport,updatethefollowingparameterinthe config\listeners.cnffileinthepackageforwhichtheportisdefined:
<array name="hostAllow" type="value" depth="1"> <value>132.906.19.22</value> </array>
To allow inbound requests from only specified hosts 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickPorts. ClickChange Global IP Access Restrictions. ClickChange IP Access Mode to Deny by Default. Theserverchangestheaccessmodeanddisplaysascreenfromwhichyoucanadd hoststotheAllowList.Noticethattheserverhasalreadyincludedthehostnameand IPaddressofthemachinefromwhichyouareusingtheIntegrationServer Administratorsothatyouarenotlockedoutoftheserver. 5 ClickAdd Hosts to Allow List.
160
Specifythehostnames(e.g.,workstation5.webmethods.com)orIPaddresses(e.g. 132.906.19.22)ofhostsfromwhichtheserveristoacceptinboundrequests.Separate yourentrieswithcommas,forexample:*.allowme.com, *.allowme2.com. Note: IPaddressesarehardertospoof,andthereforemoresecure. Youcanusethefollowingpatternmatchingcharacterstoidentifyseveralclientswith similarhostnamesorIPaddresses. Char * ? Description Matchesanynumberofcharacters Matchesanysinglecharacter Example r*.webmethods.com workstation?.webmethods.com
ClickAdd Hosts.
Deny Inbound Connections from Specified Hosts (Allow All Others)

ThefollowingproceduredescribeshowtochangetheglobalIPaccesssettingtoAllowby Defaultandspecifysomehoststodeny. Withthissettingineffect,theserverallowsmosthostsanddeniessome. To deny inbound requests from specified hosts 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickPorts. ClickChange Global IP Access Restrictions. ClickChange IP Access Mode to Allow by Default. Theserverchangestheaccessmodeanddisplaysascreenfromwhichyoucanadd hoststotheDenyList. 5 6 ClickAdd Hosts to Deny List. Specifythehostnames(e.g.,workstation5.webmethods.com)orIPaddresses(e.g. 132.906.19.22)ofhostsfromwhichtheserveristodenyinboundrequests).Separate yourentrieswithcommas,forexample:*.denyme.com, *.denyme2.com. Note: IPaddressesarehardertospoof,andthereforemoresecure. Youcanusethefollowingpatternmatchingcharacterstoidentifyseveralclientswith similarhostnamesorIPaddresses.
161
Char * ? 7
Description Matchesanynumberofcharacters Matchesanysinglecharacter
Example r*.webmethods.com workstation?.webmethods.com
ClickAdd Hosts
Controlling IP Access to Individual Ports

ThissectiondescribeshowtochangetheIPaccesssettingsforindividualports.
Allow Inbound Requests from Specified Hosts (Deny All Others)

ThefollowingproceduredescribeshowtochangetheIPaccesssettingsforanindividual porttoAllowbyDefaultanddenysomehosts. Withthissettingineffect,theserverdeniesmosthostsandallowssomethroughthis port. Important! BeforeyouswitchtheportsettingtoDenybyDefault,makesureyouhave atleastoneotherportthatallowsatleastonehost.Ifyouinadvertentlylockallhosts outoftheserver,youcancorrecttheproblembymanuallyupdatingtheappropriate configurationfile,asshownbelow. Before updating these configuration files, be sure to shut down the Integration Server Toresettheglobalsetting,updatethewatt.server.hostAllowparameterinthe server.cnffile.Forexample:
watt.server.hostAllow=132.906.19.22
Toresetanindividualport,updatethefollowingparameterintheconfig/listeners.cnf fileinthepackageforwhichtheportisdefined:
<array name="hostAllow" type="value" depth="1"> <value>132.906.19.22</value> </array>
162
To allow inbound requests from only specified hosts 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickPorts. LocatetheportinthePort ListandclickEditintheIP accesscolumn. ClickChange IP Access Mode to Deny by Default. Theserverchangestheaccessmodeanddisplaysascreenfromwhichyoucanadd hoststotheAllowList.Noticethattheserverhasalreadyincludedthehostnameand IPaddressofthemachinefromwhichyouareusingtheIntegrationServer Administratorsothatyouarenotlockedoutoftheserver. 5 6 ClickAdd Hosts to Allow List. SpecifythehostnamesorIPaddressesofclientsfromwhichtheserveristoaccept inboundrequests(e.g.,workstation5.webmethods.com).Separateyourentrieswith commas,forexample:*.allowme.com, *.allowme2.com. Youcanusethefollowingpatternmatchingcharacterstoidentifyseveralclientswith similarhostnamesorIPaddresses. Char * ? 7 Description Matchesanynumberofcharacters Matchesanysinglecharacter Example r*.webmethods.com workstation?.webmethods.com
ClickAdd Hosts.
Deny Inbound Requests from Specified Hosts (Allow All Others)

ThefollowingproceduredescribeshowtochangetheIPaccesssettingsforanindividual porttoDenybyDefaultandallowsomehosts. Withthissettingineffect,theserverallowsmosthostsanddeniessomethroughthis port. To deny inbound requests from only specified hosts 1 2 3 4 5 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickPorts. LocatetheportinthePort ListandclickEditintheIP accesscolumn. ClickChange IP Access Mode to Allow by Default. ClickAdd Hosts to Deny List.
163
SpecifythehostnamesorIPaddressesofhostsfromwhichtheserveristodeny inboundrequests(e.g.,workstation5.webmethods.com).Separateyourentrieswith commas,forexample:*.denyme.com, *.denyme2.com. Youcanusethefollowingpatternmatchingcharacterstoidentifyseveralclientswith similarhostnamesorIPaddresses. Char * ? Description Matchesanynumberofcharacters Matchesanysinglecharacter Example r*.webmethods.com workstation?.webmethods.com
ClickAdd Hosts.
Restricting the Services Available from a Port

Bydefault,theIntegrationServerprovidesanHTTPportat5555thatallowsallservice requeststhatcomeinonthatportaccess(unlessprohibitedbyanACL).Althoughthis portisidealforinitialIntegrationServerinstallationandconfiguration,aswellasmany developmentenvironments,fordeployment,youshouldreplacethisportwithportsthat limitaccesstoservicesyouintendtomakeavailabletoyourpartnersandusers. Therearetwotypesofportaccess: Deny By Default.Thisisthedefaulttypefornewlycreatedports.Usethistypetodeny accesstoallservicesexceptthoseyouspecifyinalistthatisassociatedwiththeport. YoumightuseaDenyByDefaultporttorestrictaccesssoonlythesetofservicesthat asingleapplicationusesareaccessiblethroughtheport.SettheporttoDenyBy Defaultandspecifytheservicesfortheapplicationinthelistassociatedwiththeport. Then,clientsusingtheapplicationcanonlyaccessthespecificservicesforthe application.Allports,except5555,areinitiallysettoDenyByDefaultwithalimited listofservicesavailable. Allow By Default.Selectthistypeifyouintendtoallowaccesstoallservicesexcept thoseyouexplicitlydenyinalistthatisassociatedwiththeport. Note: Anotherwaytocontrolaccesstoservicesthroughaportistorestrictaccessto clientsthatpresentparticularclientcertificates.SeeChapter 13,Authenticating Clientsformoreinformation.
164
Allow Access to Specified Services (Deny All Others)

Withthissettingineffect,theserverdeniesaccesstomostservicesandallowsaccessto some.Thisisthedefaultsetting. Important! Whenperformingthefollowingprocedure,donotlogintotheserver throughtheportyouwanttochange.Theprocedureinvolvestemporarilydenying accesstoallservicesthroughtheport.Ifyoulogonthroughtheportyouwantto changeandthendenyaccesstoallservicesthroughit,youwillbelockedoutofthe server.Instead,logonthroughadifferentexistingportorcreateanewporttologon through. To allow access to specified services 1 2 3 4 5 6 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecurity menuintheNavigationpanel,clickPorts. IntheAccess Modecolumn,clickEditfortheportwithwhichyouwanttowork. ClickSet Access Mode to Deny by Default. ClickAdd Folders and Services to Allow List. Buildalistoffoldersandservicesfortheservertoallowfromthisport. Youcanbuildthelistbyenteringonefolderorserviceatatime,enteringsetsof foldersorservices,ordoingacombinationofthetwo.Typically,youwillgroup theservicesyouwanttoexposetoyourpartnersinoneormorefolders.Itisthen asimplematterofaddingthosefolderstothelist. Toenterfoldersorservicesoneatatime,enterthefolderorservicenameinthe areaprovidedontheleftandclickENTER.Repeatuntilyouhaveaddedallthe foldersandservicesyouwanttoadd. Alternatively,youmightwanttoallowallservicesassociatedwithaspecific ExecuteACL.Forexample,tocreateacustomAdministratorport,youcanexpose allservicesprotectedbytheAdministratorsACL. ToenterasetofservicesorfoldersassociatedwithanACL,usetheSelect an ACL listontherightofthescreentoselectanACL.Theserverdisplaysalistofthe foldersandservicesprotectedbytheACL.Initially,alltheseitemsareselected.If youdonotwanttoaddallofthemtothelist,deselecttheonesyoudonotwant. (UseCtrlClicktodeselectaselecteditem.)Tomovetheseentriestothelistof foldersandservicesthatwillbeaccessiblethroughtheport,clickAppend Selected. Theserverappendstheselectedentriestotheexistinglist. 7 Continuetheprocessofaddingindividualitemsand/orsetsofitemsuntilyouhave builtthelistoffoldersandservicesyouwanttomakeavailablefromthisport.Then clickSave Additions. ClickReturn to Ports toreturntothe Security > Ports > Edit Access Modescreen.
165
Deny Access to Specified Services (Allow All Others)

Withthissettingineffect,theserverallowsaccesstomostservicesanddeniesaccessto some. To deny access to specified services 1 2 3 4 5 6 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecurity menuintheNavigationpanel,clickPorts. ClickEditintheAccess Modecolumnfortheportwithwhichyouwanttowork. ClickSet Access Mode to Allow by Default. ClickAdd Folders and Services to Deny List. Buildalistoffoldersandservicesfortheservertodenyfromthisport. Youcanbuildthelistbyenteringonefolderorserviceatatime,enteringsetsof foldersorservices,ordoingacombinationofthetwo. Toenterfoldersorservicesoneatatime,enterthefolderorservicenameinthe areaprovidedontheleft,andpressENTER.Repeatuntilyouhaveaddedallthe foldersandservicesyouwanttoadd. Toenterasetofservicesorfolders,usethepulldownmenuontherightofthe screentoselectanExecuteACL.Theserverdisplaysalistofthefoldersand servicesprotectedbytheACL.Initially,alloftheseitemsareselected.Ifyoudo notwanttoaddallofthemtothelist,deselecttheonesyoudonotwant.(Use CtrlClicktodeselectaselecteditem.)Tomovetheseentriestothelistoffolders andservicesthatwillbeaccessiblethroughtheport,clickAppend Selected.The serverappendstheselectedentriestotheexistinglist. 7 Continuetheprocessofaddingindividualitemsand/orsetsofitemsuntilyouhave builtthelistoffoldersandservicesyouwanttodenyaccesstofromthisport.Then clickSave Additions. ClickReturn to PortstoreturntotheSecurity > Ports > Edit Access Modescreen. To reset a port to the default 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecurity menuintheNavigationpanel,clickPorts. LocatetheportwithwhichyouwanttoworkinthePort ListandclickEditinthe Access Modecolumn. ClickReset to Default Access Settings. TheIntegrationServerchangesthetypetoDenyByDefaultandcreatesadefaultlist ofallowedservices.Theseincludethestandardservicesrequiredtoconnecttoand authenticatetotheserver.
166
Controlling the Use of Directives

Adirectiveisawaytoaccessorinvokeresources.IntegrationServersupportsthese directives: Directive invoke web soap default Used to... Runservices AccessJSPfiles RouterequeststotheIntegrationServerSOAPhandler RouterequeststothedocumenthandlertheIntegrationServeruses toprocessDSPpages
Usersspecifydirectivesasfollows:
http://host:port/directive/interface/service_name
Forexample:
http://localhost:5555/invoke/wm.server/ping
Bydefault,allIntegrationServerportsexcepttheproxyportallowallthedirectiveslisted above.Theproxyportallowsalldirectivesexceptthewebdirective.However,for securityreasons,organizationstypicallyallowonlythosedirectivesthatarenecessaryto fulfillitsbusinessrequirements.Youmightfeelallowalldirectivesonportsthatare accessibleonlytouserswithinyourfirewall,butyoumightwanttorestrictdirectiveson portsthatareexposedtousersoutsidethefirewall.Forexample,ifyouwanttoreceive onlySOAPrequestsonaparticularport,frombothinternalandexternalusers,youcould allowthesoapdirectivebutnootherdirectivesonthatport.Torestricttheuseof directivestocertainportsonly,yousetthewatt.server.allowDirectiveparameter(see watt.server.allowDirectiveonpage 418). Bydefault,theinvokedirectiveisspecifiedonURLsasinvoke(thatis, http://host:port/invoke/folder/service_name).Youcanidentifyanalternativewordforusers tospecifyastheinvokedirective.Forexample,youmightwanttoallowuserstospecify theinvokedirectiveassubmit(thatis,http://host:port/submit/folder/service_name).To addanalternativewordfortheinvokedirective,yousetthewatt.server.invokeDirectory parameter(seewatt.server.invokeDirectiveonpage 429). Bydefault,thesoapdirectiveisspecifiedonURLsassoap(thatis, (http://host:port/soap).Youcanidentifyadifferentwordforuserstospecifyforthesoap directiveinstead.Forexample,youmightwantuserstospecifythesoapdirectiveas endpoint(thatis,http://host:port/endpoint)insteadofsoap.Tospecifyadifferent wordforthesoapdirective,yousetthewatt.server.SOAP.directiveparameter(see watt.server.SOAP.directiveonpage 436).
167
Controlling Access to Resources with ACLs

YoucanuseAccessControlLists(ACLs)tocontrolaccesstopackages,folders,files, servicesandotherelementsthatresideontheIntegrationServer.Specifically,youcan controlaccessto: Services clients can invoke.Youcancontrolwhichgroups(andthereforewhichusers) caninvokeaservice.InadditiontocheckingACLstodeterminewhetheraclientcan invokeaservice,theserverperformsanumberofportlevelchecks.SeeControlling AccesstoResourcesbyPortonpage 158foradescriptionofthesechecksandhow youcanconfiguretheservertoperformthem. Special tools such as the Integration Server Administrator, the Developer, and replicator functions.ThesespecialabilitiesaregrantedbytheAdministrator,Developer,and ReplicatorACLsthatareprovidedwiththeIntegrationServer. Elements that developers can see and use.Youcanfinetunecontroloverwhich developershaveaccesstowhichpackages,folders,andotherelements.Forexample, onedevelopmentgroupmighthaveaccesstocreate,update,andmaintainonesetof services,whileanotherdevelopmentgrouphasaccesstoadifferentset.ACLscan preventonedevelopmentgroupfromaccidentallyupdatingordamagingtheworkof anothergroup. Files the server can serve.Theservercanservefiles(forexampleDSPand.htmfiles) thatresideinthepubdirectoryforapackageorasubdirectoryofthepubdirectory. YoucancontrolaccesstothesefilesbyassigningACLstothemin.accessfiles.See AssigningACLstoFilestheServerCanServeonpage 177formoreinformation aboutmakingfilesavailable. ThissectiondescribeshowtocontrolaccesstoresourcesusingACLs.Tocontrolaccessat theportlevel,seeControllingAccesstoResourcesbyPortonpage 158.
About ACLs
ACLscontrolaccesstopackages,folders,andotherelements(suchasservices,document types,andspecifications)atthegrouplevel.AnACLidentifiesgroupsthatareallowedto accessanelement(AllowedGroups)and/orgroupsthatarenotallowedtoaccessan element(DeniedGroups).WhenidentifyingAllowedGroupsandDeniedGroups,you selectfromgroupsthatyouhavepreviouslydefined. Therearefourdifferentkindsofaccess:List,Read,Write,andExecute. Listallowsausertoseethatanelementexists.Theelementwillbedisplayedon screensintheDeveloperandtheIntegrationServerAdministrator.Listaccessalso allowsyoutoviewanelementsmetadata. ReadallowsausertoviewthemainsourceofanelementthroughtheDeveloperand IntegrationServerAdministrator.
168
Writeallowsausertoeditanelement.Thisaccessalsoallowsausertodeleteorlock anelementortoassignanACLtoit. Executeallowsausertoexecuteaservice.Thisaccessalsogivestheuseraccesstofiles theserverserves,suchasDSPand.htmfiles. List,Read,andWriteACLsareusedmostlyduringdevelopmenttimebydevelopers,and tosomeextentserveradministrators,whoneedaccesstocreate,edit,andmaintain servicesandotherelements.Executeaccessisusedextensivelyinproduction environments. Whenausertriestoaccessanelement,theservercheckstheappropriateACL(List,Read, Write,orExecute)associatedwiththeelement. YoucannotassignanACLtoanelementunlessyouareamemberofthatACL.For example,ifyouwanttoallowDevTeam1toupdatetheOrderFormservice,youmustbea memberoftheDevTeam1ACL.Inotherwords,yourusernamemustbeamemberofa groupthatislistedintheDevTeam1ACL.Similarly,whenyouchangeanACL assignmentforanelement,youmustbeamemberoftheexistingACLandamemberof theACLtowhichyouareassigningtheelement. Thefollowingtablesummarizeswhatthedifferentaccesstypesmeanforthedifferent elements. Type of access and allowed actions Element Package List Read Write N/A Execute N/A
Seethatthe N/A packageexists.To seewhatthe packagecontains, youmusthave Listaccesstothe elements themselves.This accessisnot inheritedby otherelementsin thepackage.
169
Type of access and allowed actions Element Folder List Seethatthe folderexists. Childrenwill inheritListaccess iftheydonot haveaspecific accessoftheir own. Read Hasno meaningfor thefolder itself. Childrenwill inheritRead accessifthey donothavea specific accessof theirown. Write Addan elementtoor deletean elementfrom thefolder. Changethe ACL assignmentfor thefolder. Childrenwill inheritWrite accessifthey donothavea specificaccess oftheirown. Execute Hasno meaningfor thefolder itself. Childrenwill inherit Execute accessifthey donothavea specific accessof theirown.
Services (includesFlow, Java,C,XSLT, Adapter services,and Webservice descriptor)
Seethatthe serviceexists.In theDeveloper, tabsforthe servicewillbe listedand information underthetabs willbeshownfor nonsourcetabs. Seethatthe elementexists.
Seethe services sourceinthe Developer.
Edit,lock, Executethe unlock,and service. deletethe service.Change theACL assignmentfor theservice.
Specifications, Schemas,Flat FileSchemas, Document Types,Adapter Notifications, Triggers
Seethatthe element exists.Fora trigger,see thedefined conditions.
Edit,lock, unlock,and deletethe element. Changethe ACL assignmentfor theelement.
N/A
Package Replication
Forpackagereplication,thepublishingservermakessurethattheuserperformingthe replicationhasreplicationaccess;thatis,theuserisamemberoftheReplicatorACL. Inaddition,thepublishingusermusthaveListaccesstothepackagetoseeitfromthe publishingscreensoftheIntegrationServerAdministrator.ThisListACLtravelswith thepackagetothesubscribingserver.ACLsdonottravelwithothernamespace elements,suchasfolders,services,etc.
170
Onthesubscribingserver,theuserinstallingthepackagemusthaveListaccesstoseeit fromtheInstall Inbound Releasesscreen.ThismeansthattheACLmustexistonthe subscribingserverandtheinstallingusermustbeamemberofthatACL.Theinstalling userdoesnotneedWriteaccesstothepackage.
Implicit and Explicit Protection

IftheelementisexplicitlyprotectedbyanACL,theserverchecksthedesignatedACL. IftheelementisnotexplicitlyprotectedbyanACL,thefollowinghappens: Forelements(otherthanfiles),iftheparentfolderisprotectedbyanACL,the elementinheritsthefoldersprotection.Ifthefolderhasnoexplicitprotection,the elementinheritstheprotectionofthefoldersparent. Forfiles,iftheparentfolderisprotectedbyanACL,thefileinheritsthefolders protection.However,ifthefileresidesinasubfolderthatisnotexplicitlyprotectedby anACL,theserverassignstheDefaultACLtothefile.Formoreinformationabout files,refertoAssigningACLstoFilestheServerCanServeonpage 177. LikenamedfoldersindifferentpackagessharethesameACL.Forexample,ifboththe FinanceandMarketingpackagescontainatoplevelfoldernamedMonthEnd,both versionsofthefolderarecontrolledbythesameACL,eventhoughthefoldershave differentcontents. Note: ToplevelfoldersneverinheritListaccessfromtheparentpackage.
Users that Belong to More than One Group

Ausercanbeamemberofoneormoregroups.Thefollowingtablesummarizeshowthe serverhandlesaccessforauserthatisamemberofasinglegroup.Accesscanbeanyof List,Read,Write,orExecute. If a client is a member of a group that is: Allowed Denied Not-specified Access to the package, folder, or other element is: Allowed Denied Denied
Note: Theserverusesthefollowingruletodetermineaccessforauserthatisa memberofmorethanonegroup:iftheuserbelongstoanygroupthatisallowed,and tonogroupthatisdenied,theuserisallowed.Otherwisetheuserisdenied.
171
ThefollowingtablesummarizesthisapproachforauserthatisamemberofbothGroup1 andGroup2.AccesscanbeanyofList,Read,Write,orExecute: Group1s access to the package, folder, or other element Allowed Group2s Access to package, folder, or other element Allowed Denied Not specified User Allowed User Denied User Allowed Denied User Denied User Denied User Denied Not specified User Allowed User Denied User Denied
Predefined ACLs
TheservercomeswiththefollowingpredefinedACLs.YoucannotdeletetheseACLs. Administrators.AllowsonlyusersintheAdministratorsgroupaccesstoapackage, folder,orotherelementanddeniesallotherusers. Anonymous.Providesaccesstounauthenticatedusers(thosethatdidnotspecifya validuserid). Default.Allowsallauthenticatedusersaccesstoapackage,folder,orotherelement. WhenanelementisnotspecificallyassignedanACLordoesnotinheritanACLfrom containingfolders,theserverusestheDefaultACL.IftheACLassignedtoan elementisdeleted,theserverusestheDefaultACL.TheDefaultACLauthorizes authenticatedusersonly.Unauthenticatedusers(thosethatdidnotspecifyavalid userid)areauthorizedbytheAnonymousACL. Developers.AllowsonlyusersintheDevelopersgroupaccesstoapackage,folder,or otherelementanddeniesallotherusers. Internal.AllowsonlyusersintheAdministratorsandDevelopersgroupsaccesstoa package,folder,orotherelementanddeniesallotherusers.Theserverassignsthis ACLtobuiltinutilityservicesshippedwiththeserver,suchasthoseintheWmRoot andWmPublicpackages.YoushouldneverneedtoassignthisACLtoanelement. Replicators.AllowstheReplicatoruserreplicationprivileges. Note: YoumightseeanACLthatisspecificforanadapter,forexamplethe wmPartnerUsersACL.Refertothedocumentationforthespecificadapterformore informationaboutitsACL.
172
When Does the Server Perform ACL Checking?

TheIntegrationServerchecksACLswhen: AclientoraDSPinvokesaservicethatresidesontheIntegrationServer.Aclientcan beabrowseruser,anotherIntegrationServer,anISclient(usingtheISclientAPI),or acustomHTTPclient. YouareusingtheDevelopertoolandyoutrytoaccess(list,create,update,seethe sourceof,delete,orchangetheACLassignmentsof)anelement. YouareusingtheIS AdministratorandyoutrytolistorchangetheACLassignment ofanelement. Bydefault,theIntegrationServerperformsACLcheckingagainstexternallyinvoked servicesonly.Externallyinvokedservicesarethosethataredirectlyinvokedbyaclient orDSP.Youcan,however,configureaservicetohaveitsACLcheckedevenifitis internallyinvoked,thatis,invokedbyanotherservicerunningontheIntegrationServer. TodirecttheservertocheckaservicesACLevenwhentheserviceisinternallyinvoked, usewebMethodsDeveloper,locatetheservicesPermissionscreen,andsettheEnforce Execute ACL optiontoAlways.SeethewebMethodsDeveloperUsersGuideformore information.
Creating ACLs
WhencreatinganACL,youselectgroupstousefortheAllowedGroupsandDenied Groupsfrompreviouslydefinedgroups. To create an ACL 1 2 3 4 5 OpenIntegrationServerAdministratorifitisnotalreadyopen. IntheSecurity menuoftheNavigationpanel,clickACLs. ClickAdd and Remove ACLs. SpecifyoneACLnameperline.PressENTERtoseparatethelines. ClickCreate ACLs.
173
Allowing or Denying Group Access to ACLs

YoucaneditaneworpredefinedACLtoallowcertaingroupstoaccessthisACLand denypermissionstoothergroups.Youcanallowanddenyaccesstointernallydefined groupsaswellasgroupsandrolesdefinedexternallyinacentraluserdirectoryorin LDAP. To allow group access to an ACL 1 2 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecurity menuoftheNavigationpanel,clickACLs. Theserverdisplaysthe AccessControlListsscreen. GroupsintheAllowedlistareexplicitlyallowedtoaccessthepackages,folders, services,orotherelementsassociatedwiththisACL. GroupsintheDenied listareexplicitlydeniedaccesstothepackages,folders, services,orotherelementsassociatedwiththisACL 3 4 IntheSelect ACLlistunderACLMembership,selecttheACLtowhichyouwantto addgroups. Dooneofthefollowing: IfyouwanttoallowagrouporroleaccesstothisACL,undertheAllowedlist,click Add. IfyouwanttodenyagrouporroleaccesstothisACL,undertheDeniedlist,click Add. 5 Inthedialogboxthatappears,intheProviderlist,selectthelocationfromwhichyou wanttoselectausergroup. Ifanexternaluserdirectoryisnotconfigured,theProviderlistdoesnotappear. 6 IntheRole/Group Name list,dooneofthefollowing: IfyouselectLocal,selectthelocallydefinedusergroupforwhichyouwantto allowordenyaccesstotheACL. IfyouselectCentralorLDAP,intheSearchfield,entersearchcriteriaforfindinga roleorgroup.ClickGo.Selecttheroleorgroupforwhichyouwanttoallowor denyaccesstotheACL. 7 ClickSave Changes.
Deleting ACLs
YoucandeleteanyACLexceptthepredefinedACLs:Anonymous,Administrators, Default,Developers,Internal,andReplicators.YoucandeleteACLsthatarecurrently assignedtopackages,folder,orotherelements.Whenaclientattemptstoaccessan elementthatisassignedtoadeletedACL,theserverdeniesaccess.
174
WhenyoudeleteanACLthatisassignedtoapackage,folder,serviceorotherelement, theIntegrationServerretainsthedeletedACLsname.Asaresult,whenyouviewthe elementsinformation,theserverdisplaysthenameofthedeletedACLintheassociated ACLfield;howevertheservertreatstheACLasanemptyACLandallowsaccesstono one. ForinformationabouthowtoassignadifferentACLtoapackage,folder,service,or otherelement,seeAssigningACLstoFolders,Services,andOtherElementson page 176. ForinformationabouthowtoassignadifferentACLtofile,thatis,aDSPor.htmfilethat theserverserves,updatetheassociated.accessfiletoassignadifferentACLtothefile. FormoreinformationaboutassigningACLstofiles,seeAssigningACLstoFilesthe ServerCanServeonpage 177. To delete an ACL 1 2 3 4 5 6 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecurity menuoftheNavigationpanel,clickACLs. Click Add and Remove ACLs. Inthe Remove ACLs areaofthescreen,selecttheACLorACLsyouwanttoremove. Click Remove ACLs. Theserverissuesaprompttoverifythatyouwanttodeletethe ACL. ClickOKtodeletetheACL.
Default Settings and Inheritance

Thissectiondescribesthedefaultsettingsfornewlycreatedpackages,folders,andother elementsandhowafoldersACLassignmentsaffecttheelementsitcontains.For example,ifyoucreateaserviceanddontexplicitlyassignanyACLstoit,whatdoesthe serveruseforthatservicesACLassignments?Ingeneral,itworksasfollows: Whenyoucreateapackage,theserverassignsDefaultfortheListACL.(Packagesdo nothaveRead,Write,orExecuteACLs).Thismeansthatanyauthenticatedusercan seethatthepackageexists. Whenyoucreateatoplevelfolder,thatis,onethatisnotcontainedinanotherfolder, theserverassignsDefaultfortheList,Read,andWriteACLs,andInternalforthe ExecuteACLtothefolder.Thismeansthatanyauthenticatedusercanseethatthe folderexists.TheReadandExecuteACLshavenomeaningforthefolderitself.They aretherejustforinheritancepurposes.Inotherwords,elementsinthefolderwill inheritthosesettings. Whenyoucreateasubfolderorotherelement(service,schema,specification, documenttype,trigger,andotherelements)thefolderorotherelementinheritsits ACLsettingfromtheparentfolder.
175
Thisbehaviorissummarizedinthefollowingtable: ACL assigned by default Element Type Package Top-Level Folder Subfolder Other Element List Default Default Inherit Inherit Read N/A Default Inherit Inherit Write N/A Default Inherit Inherit Execute N/A Internal Inherit Inherit
What Happens When You Change Existing ACL Assignments

IfyouassignaspecificACLtoanelementthenlaterdecidetoremovetheACL assignment(thatis,changeittoInherited),theelementwillinherittheACLoftheparent folder.Theserverdisplays(inherited)andthenameoftheACLinheritedfromtheparent folder.IfyouremoveanACLassignmentfromatoplevelfolder,theserverusesDefault. IfyouremovetheListACLassignmentfromapackage,theserverusesDefault. Important! TheDefaultACLidentifiestheEverybodygroupasanAllowedgroupand Anonymousasadeniedgroup.ThismeansthatifanelementhasnoACLspecifically assignedtoit,thenallusersexceptunauthenticatedonescanaccesstheelement.To avoidinadvertentaccesstoresources,assignanappropriatereplacementforthe DefaultACL. IfyouchangeafoldersACLassignment,itcanchangetheACLassignmentsofthe elementscontainedwithin.Specifically,elementswhoseACLassignmentisInheritedwill changetothefoldersnewACLassignment.ElementsthatalreadyhaveaspecificACL assignmentwillremainunchanged.
Assigning ACLs to Folders, Services, and Other Elements

YoucanusetheIntegrationServerAdministratortoassignanACLtoafolder,a subfolder,oranindividualservice.Keepthefollowingpointsinmindwhenassigning ACLSusingtheIntegrationServerAdministrator: IfyouassignanACLtoafolder,allthechildreninthefolderwillinheritthatsetting unlesstheyalreadyhaveanACLexplicitlyset.Formoreinformationabout inheritance,seeDefaultSettingsandInheritanceonpage 175. YoucanonlyassignanACLtoanelementifyouareamemberofthatACL.For example,ifyouwanttoallowDevTeam1toupdatetheProcessOrderservice,youmust beamemberoftheDevTeam1ACL.Thatis,yourusernamemustbeamemberofa grouplistedintheDevTeam1ACL. Ifanelementislockedbyanotheruserorsystemlocked,youcannotchangetheACL assignedtotheelement.YoucanonlyassignanACLtoanunlockedelementoran elementlockedbyyou.
176
Note: UseDevelopertoassignACLstopackages,specifications,documenttypes, schemas,andtriggers.Formoreinformation,seethewebMethodsDeveloperUsers Guide. UsethefollowingproceduretoassignanewordifferentACLtoafolderorservice. To assign an ACL to a folder or service 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackages menuoftheNavigationpanel,clickManagement. ClickBrowse Folders. Ifthecurrentscreendoesnotlistthefolderorservicetowhichyouwanttoassignan ACL,clickthenameoftheparentfolderuntiltheserverdisplaysascreenthatlists thefolderorservicewithwhichyouwanttowork. ClickintheappropriateACLfield(List,Read,Write,orExecute). TheserverdisplaystheACL Informationscreen.Usethepulldownlisttoselectthe ACLyouwanttoassigntothefolderorserviceandclickSave Changes. To remove an ACL from a folder or service 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackages menuoftheNavigationpanel,clickManagement. ClickBrowse Folders. Ifthecurrentscreendoesnotlistthefolderorservicetowhichyouwanttoassignan ACL,clickthenameoftheparentfolderuntiltheserverdisplaysascreenthatlists thefolderorservicewithwhichyouwanttowork. ClickintheappropriateACLfield(List,Read,Write,orExecute). TheserverdisplaystheACL Informationscreen.Select<Default> (inherited)fromthepull downmenuofACLnamesandclickSave Changes.
Assigning ACLs to Files the Server Can Serve

Theservercanservefilesthatresideinthepubdirectoryforapackageorasubdirectory ofthepubdirectory.FormoreinformationabouthowtoservefilesfromtheIntegration Server,refertothewebMethodsDeveloperUsersGuide. Youcontrolaccesstofilesbyplacinga.accessfileinthedirectorythatcontainsfilesyou wanttoprotect.Youcanuseanoperatingsystemtoolofyourchoicetoeditthe.access file.
177
Note: The.accessfilescontrolaccesstofilestheserverserves,suchasDSPandHTML files.TocontrolaccesstoaservicethataDSPorHTMLfilecalls,youmustassignan ACLtotheserviceitself.SeeAssigningACLstoFolders,Services,andOther Elementsonpage 176formoreinformation. Ifthedirectorycontainssubdirectories,theywillnotinherittheprotection,soyoumust providea.accessfileineachdirectory.Foreachfileinthedirectorythatyouwantto protect,placealineinthe.accessfiletoidentifythefileandtheACLyouwanttouseto protectthefile. Forexample,assumeyouhaveadirectorythatcontainsthreefiles(adminpage.dsp, home.dsp,andindex.htm).Youwanttoprotecttheadminpage.dspfilewiththe AdministratorsACLsothatonlyadministratorscanaccessthisfile.Youwanttoprotect thehome.dspfilewiththeDevelopersACLsoonlydeveloperscanaccessthisfile.You alsowanttoassigntheDefaultACLtotheindex.htmfilesoalluserscanaccessit.To accomplishthis,youwouldplacethefollowingrecordsinthe.accessfile:
adminpage.dsp Administrators home.dsp Developers index.htm Default
Note: Intheaboveexample,becauseyouwantalluserstobeabletoaccessthe index.htmfile,youcouldomittheindex.htmDefaultfromthe.accessfile.Theserver usestheDefaultACLforfilesthatarenotidentifiedina.accessfileorallfilesina directorywithouta.accessfile. Important! TheIntegrationServerloads.accessfileswhenapackageisloaded; therefore,ifyouwantthechangesyoumaketotakeeffectimmediately,reloadthe package.
Rules for Using .access Files

Whenmakingentriesin.accessfiles,observethefollowingrules: Specifythefilenameonly,suchasadminpage.dspfollowedbytheACLname.Ifyou specifyarelativepath,thefilewillnotbeprotected.Forexample,supposefile home.dspisinsubdirectorydocsindirectorypub(pub\docs\home.dsp).Ifyouadd thefollowingentrytothe.accessfileondirectorypub,thefilewillnotbeprotected:
docs\home.dsp Developers
Instead,addthefollowingentrytothe.accessfileondirectorypub\docs:
home.dsp Developers
Thecaseinwhichyouenterthenamedependsonhowyourfilesystemhandlescase. Supposeyouhaveafilenamedindex.dsp.Ifyouuseacaseinsensitivesystemsuchas Windows,youcanenterthefilenameinanycase.ThereforeIndex.dsp,INDEX.DSP, andsoonareallacceptable.However,ifyouuseacasesensitivesystemsuchas UNIX,youmustenter index.dsp.
178
Removing ACL Protection from a File

UsethefollowingproceduretoremoveACLprotectionfromafile. To remove ACL protection from a file 1 2 3 Shutdowntheserver.Forinstructions,seeShuttingDowntheIntegrationServer onpage 37. Editthe.accessfileanddeletethelinethatspecifiesthefilewhoseACLprotection youwanttoremove. Restarttheserver.Forinstructions,seeRestartingtheIntegrationServeron page 38.
179
180
13
Authenticating Clients
182 182 186 188 188 189 195
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Client Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Importing a Client Certificate and Mapping It to a User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring How Ports Handle Client Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Basic Authentication (User Names and Passwords) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Responding to Integrated Windows Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
181
13 Authenticating Clients
Overview
ThischapterdescribeshowtheIntegrationServerprocessesrequestsfromclients attemptingtocommunicatewithit.ForinformationabouthowtheIntegrationServer behaveswhenitistheclient,seeWhentheIntegrationServerIsanSSLClienton page 147andPresentingMultipleClientCertificatesonpage 148. Authenticationisdeterminingwhoaclientis.Whentheserverperformsauthentication, itdeterminestheusernameofaclient. Authenticationworkswithaccesscontrol.Aftertheserverdeterminestheusernameofa client,itcanthendeterminewhethertheclientshouldbegrantedaccesstotherequested resource.Theserverusestheclientsgroupmembershiptocontrolaccesstotheserver resources. The server authenticates when a client attempts to Invokeaservice The server controls access to the requested resource by determining whether Theclientisamemberofagrouplistedamongthe AllowedGroupsorDeniedGroupsintheExecuteACL thatisassociatedwiththeservice. TheclientisamemberoftheAdministratorsGroup, whichindicatestheclienthasadministratorprivileges. TheclientisamemberoftheDevelopersGroup,which indicatestheclienthasdeveloperprivileges.
Accessthe Integration ServerAdministrator Connecttotheserverfrom Developer
Client Certificates
Aclientcertificateisadigitalcertificatethatidentifiesaclient.Theserverattemptsto authenticateusingclientcertificatesonlyiftheincomingrequestisanHTTPSorFTPS request. Ifaportisconfiguredtorequest(orrequire)clientcertificates,theserverrequeststhe clientcertificateduringtheSSLhandshakethattheclientandserverperformwhen initializinganSSLtransaction. AftertheSSLhandshakeiscomplete,theservertriestoauthenticatetheclientusingthe clientcertificate.Whathappensnextdependsonhowyourserverisconfiguredand whethertheportisanHTTPSorFTPSport. TherearethreeclientauthenticationsettingsthatyoucanspecifyontheConfigurean HTTPSPortandConfigureanFTPSPortscreens: None.Donotasktheclientforacertificate. Request.Asktheclientforacertificate,butallowloginwithbasicauthentication (user/passwordprompt)ifnocertificateisprovided. Require.Asktheclientforacertificate.Ifnoneisprovided,rejecttheloginrequest.
182
TheIntegrationServercanperformcertificatemapping.Withthisfeature,youstoreclient certificatesontheIntegrationServerandassociateeachcertificatewithaparticularuser. Whenaclientpresentsoneofthesecertificates,theIntegrationServerlogstheclientinas theuserthatwaspreviouslymappedtothecertificate. IftheuserisdefinedinMywebMethodsServerorinanyofthedirectoriesconfiguredin MywebMethodsServer,youcanassociateacertificateforthatuserinMywebMethods Server.PleaserefertoMywebMethodsServerAdministratorsGuideforfurtherdetails.If centralusermanagementisconfiguredinIntegrationServer,IntegrationServerwill automaticallychecktheMywebMethodsServerdatabaseforcertificatemappingswhen itcannotfindinitslocalmapping. ForHTTPSports,theIntegrationServerautomaticallychecksforamappeduserwhenit receivesaclientcertificate.ForFTPSports,bydefault,theIntegrationServerdoesnot checkforamappeduser.Thewatt.watt.ftpUseCertMapconfigurationpropertycontrols whethertheIntegrationServerperformscertificatemappingforFTPSports.Formore informationaboutmappingausertoacertificate,seeImportingaClientCertificateand MappingIttoaUseronpage 186. ThefollowingsectionsdescribehowtheIntegrationServerhandlesclientcertificatesat HTTPSandFTPSportsunderdifferentcircumstances.
HTTPS Ports
ThefollowingtableshowshowtheIntegrationServerhandlesclientrequestsreceivedat anHTTPSportwhendifferentclientauthenticationsettingsareineffect.Thesesettings arespecifiedontheConfigureanHTTPSPortscreen. Client Certificate Supplied None Loginwithuser/passwordsuppliedat prompt. Ifcertificateistrustedandmatchesa mappeduser,loginasthatuser. Ifcertificateisnottrustedordoesnotmatch amappeduser,loginwithuser/password suppliedatprompt. Ifyouhavecentralusermanagement configured,IntegrationServerwillcheckif thereisamappeduserinthecentralusers database. No Client Certificate Supplied Loginwith user/password suppliedatprompt. Loginwith user/password suppliedatprompt.
Request
183
Client Certificate Supplied Require Ifcertificateistrustedandmatchesa mappeduser,loginasthatuser. Ifcertificateisnottrustedordoesnotmatch amappeduser,rejecttheloginrequest. Ifyouhavecentralusermanagement configured,IntegrationServerwillcheckif thereisamappeduserinthecentralusers database.Ifthecertificateismappedtoa userincentraluserdatabase,itwillusethat, ifnotrejecttheloginrequest.
No Client Certificate Supplied Rejectthelogin request.
FTPS Ports
ThefollowingtableshowshowtheIntegrationServerhandlesclientrequestsreceivedat anFTPSportwhendifferentclientauthenticationsettingsareineffect. watt.ftpUseCertMap=true Certificate None Loginwith user/password suppliedat prompt. Ifcertificateis trustedand matchesamapped user,loginasthat user. Ifcertificateisnot trustedordoesnot matchamapped user,loginwith user/password suppliedat prompt. No Certificate Loginwith user/password suppliedat prompt. Loginwith user/password suppliedat prompt. watt.ftpUseCertMap=false Certificate Loginwith user/password suppliedat prompt. Acceptcertificate ifitistrusted,but ignoreuser providedin certificate.Instead, loginwith user/password suppliedat prompt. No Certificate Loginwith user/password suppliedat prompt. Loginwith user/password suppliedat prompt.
Request
184
watt.ftpUseCertMap=true Certificate Require Ifcertificateis trustedand matchesamapped user,loginasthat user.Ignore user/password suppliedat prompt. Ifcertificateisnot trustedordoesnot matchmapped user,ignore user/password suppliedat promptandreject theloginrequest. No Certificate Rejectthe loginrequest.
watt.ftpUseCertMap=false Certificate Acceptcertificate ifitistrusted,but ignoreuser providedin certificate.Instead, loginwith user/password suppliedat prompt. No Certificate Rejectthe loginrequest.
Checklist for Using Client Certificates

Task ConfiguretheservertouseSSL. Obtainthecertificatesofthe CertificateAuthoritiesthatyou wanttheservertousetovalidate clientcertificates. Notes RefertoOverviewonpage 182. Placeeachcertificateinaseparatefile.Place allthefilesinadirectorytowhichthe IntegrationServerhasaccess.Formore information,seeItemsYouNeedBefore ConfiguringPortstoRequestClient Certificatesbelow. RefertoConfiguringHowPortsHandle ClientCertificatesonpage 188. RefertoImportingaClientCertificateand MappingIttoaUseronpage 186.
Configuretheporttorequest clientcertificates. Importclientcertificatesand maptospecificuser
185
Items You Need Before Configuring Ports to Request Client Certificates

Beforeconfiguringportstorequestclientcertificates,youmustconfiguretheserverto useSSLandobtainthecertificatesthattheserverusestovalidateclientcertificates. Configure the server to use SSL.ForinformationaboutconfiguringtheservertouseSSL, seeOverviewonpage 182. CA certificates.Thesearethecertificatesthattheserverusestovalidateclient certificates.OnewaytoobtainthesecertificatesistoextractthemfromaWeb browser.MostWebbrowsersthatsupportSSLareshippedwiththecertificatesof wellknowncertificateauthorities.IfthecertificatesarenotinDERformat,usethe webMethodsCertificateToolkittoconvertthemtoDERformat. Placeeachcertificateinaseparatefile.Placeallthefilesinthesamedirectory.
Importing a Client Certificate and Mapping It to a User

Youcanimportclientcertificatesandkeepthemonfileandassociateeachcertificatewith aparticularuser.Thismappingallowsyoutocontrolwhichuseraclientlogsinasbased onthecertificateitpresents.Forexample,aparticularcertificatemaybeusedtoidentify theuserFINANCE. IntegrationServerautomaticallyperformscertificatemappingforrequestsreceivedat HTTPSports;however,forrequestsreceivedatFTPSports,IntegrationServerperforms certificatemappingonlyifthewatt.ftpUseCertMapconfigurationpropertyissettotrue. FormoreinformationabouthowclientauthenticationworksforanFTPSport,seeFTPS Portsonpage 184. ForportsconfiguredtoRequirecertificates,IntegrationServerwillsearchthisstoreof clientcertificatesforamatch.Iftheserverfindsamatch,theclientisautomatically loggedinastheuserthatismappedtothatcertificate.Ifnomatchisfound,therequest failsandtheclientisdeniedaccesstoIntegrationServer. ForportsconfiguredtoRequestcertificates,IntegrationServerwillsearchthestoreof clientcertificatesforamatch.Iftheserverfindsamatch,theclientisautomatically loggedinastheuserthatismappedtothatcertificate.Ifnomatchisfound,Integration Serverpromptstheusertoenteruseridandpasswordinformation. IfyouaregoingtoconfigureoneormoreportstoRequireclientcertificates,youmust importtheclientcertificatesyouwillacceptandmapthemtotheusersthatyouwantthe clientstologinas. EvenifyoudonotconfigureanyportstoRequireclientcertificates,youmightwantto importclientcertificatesandmapthemtouserssothatclientspresentingthese certificatescanautomaticallylogonasthoseusers. Whencentralusermanagementisconfigured,IntegrationServerwillfirstcheckthe certificatemapforausermappedtothegivencertificate.Ifnomatchisfound,
186
IntegrationServerwillthencheckthecentralusersdatabaseforausermappedtothe givencertificate.Ifitfindsausermapping,itwillusethatuser. Important! Becarefulwhenmappingausertoparticularclientcertificate.Makesure theuseryouspecifydoesnothavemoreauthoritythanyouwantitto. To import a client certificate 1 2 3 4 5 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickCertificates. ClickConfigure Client Certificates. IntheCertificate Path field,enterthepathandfilenameofthefilethatcontainsthe certificateyouwanttoimport. IntheUserfield,enterauserorclick tosearchforandselectauser.
TosearchforauserintheUser Namedialogbox,dooneofthefollowing:. Toselectalocaluser,intheProviderlist,selectLocal.Selectthelocalusertowhich youwanttomapthecertificate. Ifanexternaluserdirectoryisnotconfigured,theProviderlistdoesnotappear. Toselectauserfromanexternaldirectory(LDAPoracentraluserdirectory),in theProviderlist,selecttheuserdirectorythatyouwanttosearch.IntheSearch field,enterthecriteriathatyouwanttousertofindauser.ClickGo.Selectthe usertowhichyouwanttomapthecertificate. 6 7 IntheUsagelist,selectthepurposeforwhichyouwishtoimportthiscertificate. ClickImport Certificate. Note: ThoughIntegrationServersupportsloadingcertificatesforLDAPusers, webMethodsrecommendsusingcentralusermanagementandthenconfiguring LDAPandcertificatesinMywebMethodsServer.
Changing a Certificate Mapping

Youcanchangetheusertowhichacertificateismapped,andthepurposeforwhichthe certificateisused. To change a user mapped to a certificate 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickCertificates. ClickConfigure Client Certificates.
187
4 5 6 7 8
UnderCurrent Certificates,intheSubject CN column,clickthecertificateforwhichyou wanttochangethemapping. OntheSecurity > Certificates > Client Certificates > Details screen, clickChange Mapping. IntheUserfield,entertheusertowhichyouwanttomapthecertificateorclick searchforandselectauser. IntheUsagelist,selecttheappropriateusage. ClickSave Changes. to
Configuring How Ports Handle Client Certificates

ThissectiondescribeshowtousetheIntegrationServerAdministratortovieworchange howaporthandlesclientcertificates.Forinstructionsonaddingaport,seeChapter 7, ConfiguringPortsonpage 83. To view or change how a port handles client certificates 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheNavigationpanelofthescreen,ontheSecuritymenu,clickPorts. Locatetheportwhoseclientcertificatesettingsyouwanttovieworchangeand disableitifitisnotalreadydisabled.(Todisableaport,clickthe iconinthe Enabledcolumn.Theserverreplacesthe iconwithNotoindicatethattheportis nowdisabled.)Thenclicktheportnumber. 4 ClickEdit HTTPS Port ConfigurationorEdit FTPS Port Configurationtoupdatethe informationinthefields,asnecessary.Forfielddescriptions,seeAddinganHTTPS Portonpage 88orAddinganFTPSPortonpage 98,respectively. ClickSave Changes. EnabletheportbyclickingNointheEnabledcolumn.
5 6
Basic Authentication (User Names and Passwords)

Whentheserverusesbasicauthentication,itpromptstheclientforausernameand password.Ifauseraccountisfoundforthesuppliedusername,theserverauthenticates theusernamebycomparingthesuppliedpasswordtothepasswordintheuseraccount forthesuppliedusername.Ifthepasswordiscorrect,theserverproceedswiththe request.Ifthepasswordisnotcorrect,theserverrejectstherequest.Ifauseraccountfor thesuppliedusernameisnotfound,theserverrejectstherequest. Forsecurityreasons,theIntegrationServer(startingwithRelease4.0)storespasswords inhashedformat.Oncepasswordsarehashed,youcannotconvertthembacktoan unhashedformat.Therefore,onceyouhaveinstalledandrunwithRelease4.0orlaterof
188
theIntegrationServer,youcannotgobacktoanearlierreleaseunlessyouhavebacked upyourserver. Iftheclientdoesnotsupplyausernameorpassword,theserverusestheDefaultuser accountfortheclient. Client supplied a user name/password? YES YES YES NO User Name found? YES YES NO n/a Password correct? YES NO n/a n/a Request proceeds isrejected isrejected proceedsusingthe Defaultuseraccount
Formoreinformationonsettingupuseraccounts,seeDefiningaUserAccounton page 47.Youcanalsouseexternallydefineduseraccounts;formoreinformationonhow touseexternaldirectoriesandhowbasicauthenticationworkswhenusingexternal users,seeChapter 17,ConfiguringaCentralUserDirectoryorLDAPonpage 253.
Customizing Authentication
Theremaybetimeswhenyouneedtoperformcustomizedauthentication.Forexample, ifyouuseanexternaldirectorysuchasLDAPtostoreandmanageusersandpasswords, thepasswordsmightbeunavailabletotheIntegrationServerbecausetheyareencoded inanunsupportedformatorbecausetheyarestoredinanauthenticationsystemsuchas Kerberos. Toaccesstheseusersandpasswords,youcanwriteyourownpluggablemoduletotake overauthenticationprocessing.Theservercallsthismodulewhenthestandardmethod ofauthenticationcannotprovidethenecessaryinformation.
189
Default Authentication Processing
Successful? Yes Yes Retrieve User Information Successful? No
No
Pluggable Module (alternate authentication processing)
Access Denied
LDAP (external directory)
Authorization Processing (ACLs)
Kerberos
ThepluggablemoduleisdeployedinapackageontheIntegrationServerandconsistsof atleastafactoryclassandanauthenticationmodule. Factory class.Passestheclientprovideduseridandpasswordtotheauthentication module. Authentication module. Performstheactualauthenticationprocessing. Tomakethepluggablemoduleavailabletotheserver,youmustregisterthefactoryclass withtheserver.Thisregistrationoccursduringexecutionofastartupservicethatyou write. Note: ThereisafeatureoftheIntegrationServerthatallowsyoutomapclient certificatestoparticularusers.Thismappingallowsauserwhopresentsaparticular certificatetologonautomaticallyasthecorrespondingpremappeduser.Tousethis featureyoumustcreateandmaintainastoreofclientcertificatesontheIntegration Server.Ifyouuseanexternaldirectorytomanageusersandpasswordsandthe directorycontainscertificateinformation,youcanwriteapluggablemoduletoobtain certificateinformationdirectlyfromtheexternaldirectory.Thisapproachsavesyou frommaintainingtwocertificatestoresandallowsyoutocustomizecertificate authentication. Formoreinformationaboutmappingausertoacertificate,seeImportingaClient CertificateandMappingIttoaUseronpage 186.FormoreinformationaboutBasic Authentication,seeBasicAuthentication(UserNamesandPasswords)on page 188.
190
ThefollowingsectionsdescribehowtosetupapluggablemoduleforyourIntegration Server. Note: Ifyouaregoingtouseanexternaldirectorysuchascentralusermanagementor LDAPwiththeIntegrationServer,makesuretheserverisproperlyconfiguredto workwithanexternaldirectory.SeeChapter 17,ConfiguringaCentralUser DirectoryorLDAPforinstructions. IfyouhaveLDAPconfiguredinIntegrationServerandyoudonotrequireuserstobe authenticatedagainsttheLDAPdirectory,setthewatt.server.ldap.doNotBind propertytotruetopreventunnecessaryauthentication.
Overview of Steps
Step
1 2 3 4 5
Description Createthefactoryclass. Createtheauthenticationmodule. Createstartupandshutdownservicestoregisterandunregisterthefactory class. Placethefactoryclass,authenticationmodule,andstartupandshutdown servicesinapackage. Enablethepackage.
191
Step 1
Creating the Factory Class
Thefactoryclassinstantiatesanewinstanceoftheauthenticationmoduleforthe IntegrationServerandpassestheusernameandpasswordsuppliedbytheclienttothe module.Thefactoryclassmustimplementthecom.wm.security.auth.ModuleFactory interface.Hereisasimpleexample.

public static final void myService(IData in) throws ServiceException { // --- <<IS-START(myService)>> --String subject = null; String contenttype = null; String protocol = null; String filename = null; String sentdate = null; String recvdate = null; InputStream is = null; IDataHashCursor idhc = in.getHashCursor(); public static class TestModuleFactory implements ModuleFactory { protected TestModule _module; public TestModuleFactory() { _module = new TestModule(); } public Module getInstance() { return _module; } public static String getMechanismName() { return BasicModule.MECHANISM_NAME; } }
192
Step 2
Creating the Authentication Module
Theauthenticationmoduleperformstheactualauthenticationoftheusernameand passwordsuppliedbytheclient. Inthesimpleexamplebelow,theprocessToken(Token token)methodverifiesthatthe suppliedusersnameisbobandthatthesuppliedpasswordis123.Iftheusernameand passwordarecorrect,themethodreturnstheusernameasastringtotheIntegration Server.Theserverthencheckstomakesurethisuserexistsinitslistofusers.(Thislist consistsofusersdefinedlocallyandinexternaldirectories.)

public static class TestModule implements Module { public TestModule () { } public String processToken(Token token) { if (token == null) { return null; } String id = null;
try { BasicToken bt = ( BasicToken ) token; String name = bt. getName (); if (name == null) { return null; } if (name.equals("bob") && bt .getPassword ().equals("123") && UserManager .getUser (name) != null) id = name; } } catch ( ClassCastException cce ) { } return id; } public String getMechanism () {return "basic"; } }
Insert your own authentication processing here
Thisexampleisverysimple.Typically,ratherthancheckingforahardcodedusername andpassword,yourprocessTokenmethodwillperformauthenticationcheckingin anothersystem,suchasLDAP,orinaproprietaryorthirdpartysystem.Foranexample ofcodethatperformsthiskindofauthentication,seethesamplein WmSamples\code\source\sample\ldap.YoucanfindtheWmSamplespackageinthe certifiedsamplesareaoftheKnowledgeBaseontheAdvantageWebSite.
193
Step 3
Creating Startup and Shutdown Services to Register and Unregister the Factory Class
Tomakeyourpluggablemoduleavailabletotheserver,youmustregisterthefactory classwiththeserver.UsetheAuthenticationManager.registerMechanism methodfroma startupservicetoregistertheclass.Astartupservicerunseachtimeitsassociated packageisenabled. Whenyouenablethepackagethatcontainsyourpluggablemodule,thestartupservice executesandregistersthefactoryclass,makingthepluggablemoduletheservers alternateauthenticationprocessor.Thismeansthatiftheservercannotperform authenticationusingthedefaultwebMethodsauthentication,theserverturnsprocessing overtothepluggablemodule. Hereisasamplestartupservicethatregistersthefactoryclasswiththeserver:
public static final void registerAuth (IData pipeline) throws ServiceException { AuthenticationManager.registerMechanism(TestModuleFactory.getMechanismName(), new TestModuleFactory()); }
Youmustunregisterthefactoryclasswhenthepackagecontainingthepluggablemodule isdisabled.YoucandosobyexecutingtheAuthenticationManager.unregisterMechanism methodfromthepackagesshutdownservice.Ashutdownserviceisonethatexecutes eachtimethepackageisdisabled Hereisasampleshutdownservicethatunregistersthefactoryclassfromtheserver:

public static final void unregisterAuth (IData pipeline) throws ServiceException { AuthenticationManager.unregisterMechanism(BasicModule.MECHANISM_NAME); }
Forinformationaboutsettingupstartupandshutdownservicesforapackage,see RunningServicesWhenPackagesAreLoaded,Unloaded,orReplicatedonpage 337.

Step 4
Placing the Factory Class, Authentication Module, and Startup and Shutdown Services in a Package
Placethefactoryclass,authenticationmodule,andstartupandshutdownservicesina package.Byplacingrelatedfilesinapackage,youcaneasilymanagealltheservicesand filesinthepackageasaunit.Forexample,youcanmakethemallavailable,disablethem, refreshthem,ordeletethemwithoneaction.Additionally,ifyouhavemorethanone IntegrationServerinstalled,youcanusethepackagereplicationfeaturetocopyallthe servicesandfilesinapackagetoanotherserver.
194
Mostlikelyyouwillwanttokeepfilesandservicesrelatedtoyourpluggable authenticationmoduleinaseparatepackagefromotherapplications.Thiswayyoucan disablethosepackagesformaintenancewithoutaffectingauthenticationonyourserver.

Step 5
Enabling the Package
Tomakeyourpluggablemoduleavailabletotheserver,youmustenablethepackagein whichthemoduleresides. 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuoftheNavigationpanel,clickManagement. ClickNointheEnabledcolumnforthepackageyouwanttoenable.Theserverissuesa prompttoverifythatyouwanttoenablethepackage.ClickOKtoenablethepackage. Whenthepackageisenabled,theserverdisplaysa column. iconand Yes inthe Enabled
Formoreinformationaboutenablingapackage,seeEnablingaPackageonpage 290.
Responding to Integrated Windows Authentication

Note: ThissectionreferstotheMicrosoftInternetInformationServer(IIS);however, theinformationappliestoanyWebserverthatsupportsIntegratedWindows authentication. WhentheIntegrationServerexecutesservicesthataccessWebpages,theserveractsasa WebclientrequestinginformationfromaWebServer.Thatis,inthesesituations,the serverfunctionsmuchlikeaWebbrowser.Inmanycircumstances,aWebServer authenticatesaWebclient. MostWebserversuseBasicAuthenticationandclientcertificatestoauthenticateWeb clients.TheMicrosoftInternetInformationServer(IIS)supportsanothertypeof authentication.IISsupportsMicrosoftIntegratedWindowsauthentication.Integrated Windowsauthenticationauthenticatesauserwithoutrequiringthetransmissionof actualpasswordsorsensitiveaccountinformationacrossthenetwork.ForIIStouse IntegratedWindowsauthenticationtoauthenticateaWebclient,theWebclientmustalso supportIntegratedWindowsauthentication.TheIntegrationServercontainssupportfor IntegratedWindowsauthentication. TheIntegrationServersupportsIntegratedWindowsauthenticationontheconnection fromtheIntegrationServertoaproxy.TheIntegrationServerdoesnotsupport IntegratedWindowsauthenticationontheconnectionfromaproxytotheInternet.
195
User Name, Password, and Domain Name

ThegoaloftheIntegratedWindowsauthenticationisthesameasforanyauthentication; thatis,todeterminetheusernamefortheclientandensurethattheclientiswhoheor sheclaimstobe. IftheIntegrationServerisrunningasanNTservice,itusesthelocalsystemrightsfor authenticationwhenrespondingtoanIntegratedWindowsauthentication.Ifyoulogon asauser,theIntegrationServerusesthecredentialsassociatedwiththatlogonsession whenrespondingtoanIntegratedWindowsauthentication.
Activating Integrated Windows Authentication

YoumustactivateIntegratedWindowsauthenticationbeforetheIntegrationServercan participateinanIntegratedWindowsauthentication.Onceactivated,theIntegration ServerautomaticallyrespondstoIntegratedWindowsauthenticationrequests. Note: IntegratedWindowsauthenticationisonlyavailablewhentheIntegration ServerisrunningonNT. To activate Integrated Windows authentication 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackages menuoftheNavigationpanel,clickManagement. IftheWmWin32packageisnotalreadyenabled,enableitbyclickingNointheEnabled columnforthispackage. Inthelistofpackages,clickWmWin32. Note: TheWmWin32packageisdeprecatedasofIntegrationServer7.1. 5 6 7 8 ClickBrowse Services in WmWin32. Inthelistofservices,click wm.ntlm:reg. ClickTest reg. Theserverdisplaysthetestscreenforthewin32.ntlm.regservice. ClickTest (without inputs).TheserveractivatesIntegratedWindowsauthentication. Note: IfyouwantIntegratedWindowsauthenticationavailablewheneverthe IntegrationServerisrunning,makethewin32.ntlm:reg serviceastartupserviceforthe Win32package.Forinstructions,seethewebMethodsDeveloperUsersGuide.
196
To deactivate Integrated Windows authentication 1 2 3 4 5 6 7 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackages menuoftheNavigationpanel,clickManagement. Inthelistofpackages,clickWmWin32. ClickBrowse services in WmWin32. Inthelistofservices,click wm.ntlm:unreg. ClickTest unreg. Theserverdisplaysthetestscreenforthewin32.ntlm.unregservice. ClickTest (without inputs).TheserverdeactivatesIntegratedWindowsauthentication.
197
198
14
Securing Your Server with PKI Profiles

200 201 202 204 207 208 208 209 209 210 211 211 213 214 215 216 217 217
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring PKI System Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a PKI Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating the PKI Profile Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Connecting to and Disconnecting from the PKI System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logging in a PKI Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting a PKI Profile Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing and Updating Information for a PKI Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing or Updating PKI Profile Alias Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Determining Whether a PKI Profile Is Logged In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Recovering a PKI Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing the Password for a PKI Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Updating Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Exporting a PKI Profile from the File System to an HSM Device . . . . . . . . . . . . . . . . . . . . . . . . . Installing an Entrust PKI Proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Password Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About CRL Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
199
14 Securing Your Server with PKI Profiles
Overview
PublicKeyInfrastructure(PKI)allowsuserstoexchangeinformationsecurelyovera networkthroughtheuseofpublicandprivatekeys.PKIalsoperformsautomatickey management.TheIntegrationServerinteractswithPKIthroughprofiles. PKIprofilesprovideasecurewayofstoringkeyingmaterialneededforencrypting, decrypting,verifying,andsigningdocuments.APKIprofileisafilethatcontainsyour privatekey,usercertificate,digitalsignature,CAcertificate,certificatehistories,and otherinformation.YoucanstorePKIprofilesinyourfilesystem(as.epffiles),orforeven greatersecurity,onanHSMdevice. AnHSMdeviceprovidesasecurealternatelocationforPKIprofiles.Evenifahacker completelysubvertstheIntegrationServerandunderlyingoperatingsystem,theycannot gettheprivatekeyoutoftheHSMdevice,buttheymightbeabletogetthekeyfroman .epffile. ThePKIsystemconsistsoftheCertificateAuthorityandanLDAPDirectory.The CertificateAuthoritymanageskeysandsecuritycredentials.TheLDAPdirectorystores copiesofencryptioncertificatesassociatedwithPKIprofiles,aswellaspolicycertificates andCertificateRevocationLists(CRLs). IfyourPKIsystemadministratordoesnotallowdirectconnectionstoyourPKIsystem, youcansetupaPKIproxy.Theproxysitsbetweentheclient(inthiscaseyour IntegrationServer)andyourPKIsystemandroutesPKIXCMPmessagesbetweenthem. SeeInstallinganEntrustPKIProxyonpage 216formoreinformation.
About PKI Profiles

UsingPKIprofilesincombinationwithwebMethodsACLs,youcanperform cryptographicfunctionsusingthePKIprofile,includingencrypting,decrypting, validating,andsigningdocuments.Forexample,youmighthaveaFinancePKIprofile formembersofyourfinancedepartmentandaSalesPKIprofileformembersofyour salesdepartment.EachdepartmentcanthenusetheirownPKIprofileforsignature relatedactivities. ToadministeraPKIprofile,asecurityofficermusthaveAdministratoraccesstothe IntegrationServer.Inaddition,thesecurityofficermustknowthePKIprofiles password. ToaccessthePKIprofilesandperformcryptographicoperations,yourservicemust invokebuiltinservicesthataresuppliedbywebMethodsIntegrationServer(thepub.pki series)forthispurpose.Inaddition,yourapplicationmustrunasanIntegrationServer userthathasbeengrantedaccesstotheprofilesthroughanACL.Thatis,theusermust beamemberoftheExecuteACLforthePKIprofile. ForaPKIprofiletobeavailabletoanapplication,theprofilemustbeloggedin. Dependingonthecircumstances,youcanhaveoneormorePKIprofilesloggedinata giventime.Youcanhavemultiple.epffilesloggedinatthesametime.Dependingon
200
yourHSMdeviceyoucanhavemultipleHSMPKIprofilesloggedinatthesametime. Youcanevenhave.epfandHSMPKIprofilesloggedinatthesametime.
PKI Profile Checking Process

Thefollowingdescribeswhathappenswhenaclientsendsasecuredocumenttoan application. 1 2 3 4 5 6 Aclientrunningoutsideyourenterprisesendsasignedand/orencrypteddocument toanIntegrationServerrunninginsideyourenterprise. TheIntegrationServerpassesthedocumenttoanapplication. Yourapplicationcallsthepub.pkiservices(providedintheWmPKIpackage)toaccess thePKIprofiles. TheserververifiesthattheuserassociatedwiththerequestisamemberofthePKI profilesExecuteACL. Theserverdecryptsandverifiesthedocumentusingthekeysandcertificatesinthe PKIprofile.ThePKIprofileresideseitherinthefilesystem,oronanHSMdevice. Theapplicationprocessesthedocumentandsendsaresponsebacktothesending client.
Supported Hardware and Software

ThewebMethodsWmPKIpackagesupportsthefollowingsoftwareandhardware: Software:EntrustAuthoritySecurityToolkitforJava7.2 Hardware (HSM device):AnyhardwaredevicethatconformstothePKCS11open standard,forexample,nCipherHSMdevices.
Getting Started
ThefollowingsectionoutlinesthestepsrequiredtosetupyoursystemtousePKI profiles: 1 2 InstallthePKIsystemaccordingtovendorinstructions. IfyourPKIsystemadministratordoesnotallowdirectconnectionsfromclients, installaPKIproxyserver,accordingtothevendorsinstructions.SeeInstallingan EntrustPKIProxyonpage 216formoreinformation. (Optional)InstallanHSMdeviceonthemachineonwhichyourIntegrationServer runs,accordingtothevendorsinstructions. Important! Thelibrarymustresideinyouroperatingsystempath.
201
InstalltheWMPKIpackageontheIntegrationServer(ormakesureitwasinstalled whenyouinstalledtheserver).GotothePackages > Managementscreenonthe IntegrationServerAdministratorandlookforWmPKIinthelistofpackagesorcheck theIntegrationServer_directory\packagesdirectory. ConfigurethePKIsystemsettingsfromtheIntegrationServer.Inthisstepyou specifyPKIconnectionsettings.SeeConfiguringPKISystemSettingsbelowfor instructions. CreatePKIprofilesiftheywerenotpreviouslycreatedusinganothertool. InthisstepyouusetheactivationcodesyouobtainedfromyourRegistration AuthoritytocreatePKIprofiles.SeeCreatingaPKIProfileonpage 204for instructions.
Instructyourdevelopmentstafftowriteorupdateapplicationstousethebuiltin publicservicesinyourWmPKIpackage(thepub.pkiseries).Thesebuiltinservices enableyourapplicationtotheaccessPKIprofilesandperformcryptographic operations.Formoreinformationaboutusingtheseservices,seethewebMethods IntegrationServerBuiltInServicesReference.
Configuring PKI System Settings

ThereareanumberofsettingsyoucanconfigureintheIntegrationServerforhowyour serverconnectstoyourPKIsystem: WhetherornottoconnecttheservertothePKIsystem LocationofthePKIsystemcomponents WhethertheserveristoperformCRLchecking WhethertoconnecttothePKIsystemdirectlyorthroughaproxy NameandlocationoftheHSMdevicelibrary To configure PKI System Settings 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheAdaptersmenuoftheNavigationpanel,clickPKI. InthePKImenu,clickPKI System Properties.
202
ClickEdit System Properties andupdatethefollowingsystempropertiesasneeded. Field Connect to PKI System Contents WhetherornottheservershouldconnecttoyourPKI system.Theserverneedstobeconnectedtoboththe CertificateAuthorityandLDAPdirectoryportionsofyour PKIsystemforprofilecreation,profilerecovery,key updates,andCRLchecking. Entrust Authority Host:Port # Hostname(IPaddress)andportoftheserveronwhichthe PKIauthorityruns,forexample,127:0.0.1:829. LDAP Directory Host:Port Hostname(IPaddress)andportoftheLDAPdirectory associatedwithyourPKIauthority,forexample 127:0.0.1:389. TheLDAPdirectorycontainscopiesofencryption certificatesassociatedwithyourPKIprofiles.Italso containsthepolicycertificateandCRLs. Note: WhentheIntegrationServerattemptstoconnectto theLDAPdirectory,thewatt.security.pki.jnditimeout propertyspecifieshowlongtheIntegrationServerwaits fortheconnectiontosucceed.Iftheconnectionfails,you willneedtoreattemptyouractionlater.Formore information,seeAppendix B,ServerConfiguration Parameters. Use HTTP Proxy Selectthisoptionif youareusingthe PKIproxy Entrust Authority Host Hostname(IPaddress)oftheserveronwhichthePKI authorityisrunning.Theproxyconnectstothishost. Proxy Entrust Authority URL URLoftheproxytoyourPKIauthority. Proxy LDAP Directory URL URLoftheproxytoyourPKIauthoritysLDAPdirectory.
Connect Directly Selectthisoptionif youarenotusingthe PKIproxy
203
Field Enable CRL Checking
Contents WhetherornotyouwanttheIntegrationServertoperform arevocationcheckagainstcertificates. CRLcheckingisperformedonlyforinternalcertificates, thatis,certificatesissuedbyyourPKIsystemscertificate authority IfCRLcheckingisenabledandtheserverencountersa revokedcertificate,theserverrejectsthecertificate(andthe request)andissuesanerrormessage. Note: IfyourserverwillbedisconnectedfromthePKI systemforlongperiodsoftime,disableCRLchecking. SeeAboutCRLCheckingonpage 217formore informationaboutthistopic.
Hardware Device Library Name
ThisisthenameofthefilethatcontainsthePKCS#11 sharedlibrary.Thislibrary(forexamplecknfast.dll)is suppliedbyyourHSMvendorandallowsyourIntegration ServertocommunicatewiththeHSMdevice.
ClickSave Changes. Important! Thelibrarymustresideinyouroperatingsystempath.
Creating a PKI Profile

Inthisstepyoucreatethefilethatcontainsyourkeysandcertificates.Thisfilewillreside inyourfilesystemasa.epffileoronyourHSMdevice. Important! YourservermustbeconnectedtoyourPKIsystemwhenyoucreateaPKI profile. TherearetwomainstepstosettingupaPKIprofile: 1 CreateaPKIprofile ThisstepcreatesyourPKIprofileusingtheactivationcodessuppliedbyyour RegistrationAuthority(RA).Theserverwritesthefiletoyourfilesystemasa.epffile ortoyourHSMdevice. 2 CreateanaliasforthePKIprofileintheIntegrationServer. InthisstepyoucreateanaliasforthePKIprofileanddefineACLassociationsanda listoftrustedcertificatesforit.
204
Thesestepsaredescribedbelow. Important! BeforecreatingaPKIprofile,youmusthavetheRegistrationAuthority createtheuser.Whensupplyinginformationabouttheuser,donotusemultibyte characters.Multibytecharactersarenotsupported. To creating a PKI Profile

Cre
IfyouarestoringthePKIprofileonanHSMdevice,makesureapreformattedtoken hasalreadybeeninsertedintoaslotinthedevice.Thetokenshouldbeemptyexcept foralabelandapassword.ClickView Label Informationtodisplayalistoftokens(and theirlabels)currentlyinsertedintheHSMdevice. OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheAdaptersmenuoftheNavigationpanel,clickPKI. InthePKImenu,clickProfile Management. ClickCreate PKI Profile. Updatetheprofilesettingsasfollows: Field Activation Codes from Registration Authority Contents Reference Number Referencenumberprovidedbyyourregistrationauthority. Authorization Code Authorizationcodeprovidedbyyourregistrationauthority. PKI Profile Location File System Enterinformationinthesefieldsonlyifyouwanttostorethe PKIprofileinyourfilesystem. File Name Nameofthe.epffile.Youcanspecifyanabsoluteorrelative path.Ifyouspecifyjustthefilename,theserverwritesthe PKIprofiletotheserverrootdirectory.Besuretospecifya paththatisvalidandaccessibletotheserver. Password PasswordyouwanttoassociatewiththePKIprofile.This passwordisrequiredwhenyouloginaPKIprofile.There maybetimeswhentheserverasksyoutochangea password.SeePasswordRulesonpage 217formore information. Confirm Password Enterthesamepasswordagaintomakesureyoutypedit correctly.
2 3 4 5 6
205
Field Hardware Device
Contents Enterinformationinthesefieldsonlyifyouwanttostorethe PKIprofileonanHSMdevice. Label LabelofthetokentoassociatewiththisPKIprofile.Toseea listoftokens(andtheirlabels)currentlyinsertedintothe HSMdevice,clickView Label Information.Later,whenyoulog inthePKIprofile,theserverwillsearcheachslotintheHSM deviceuntilitfindsatokenwiththislabel. Password PasswordassociatedwiththePKIprofile.Thispassword wasassignedtothetokenwhenitwasformatted. Use Auxiliary Profile CreatesanauxiliaryPKIprofile,whichstoresinformation aboutpreviousdecryptionkeyupdates.Theserverusesthis filewhendecryptingmessagesthatwereencryptedwithan oldkey. Path to Auxiliary Profile PathtotheauxiliaryPKIprofilefortheHSMdevice(see below).Besuretospecifyapaththatisvalidandaccessible totheserver. Auxiliary Profile Name NameoftheauxiliaryfilefortheHSMdevice.Thisfile residesinthefilesystemandcontainsahistoryofall decryptionkeyscreated.Whenyouperformakeyupdate, thenewdecryptionkeyisaddedtothefile.Theserveruses thisfilewhendecryptingmessagesthatwereencryptedwith anoldkey.
Key Information
Key Strength Strengthofthesigningandencryptionkeys,measuredas thenumberofbitsinthepublicorprivatekeys.Select1024 or2048.1024isthedefault.Alargersizeincreasesthe strengthofencryption,butcanslowperformance. Key Pair Algorithm Encryptionalgorithmtouseforthesigningandencryption ofkeys.SelectRSAorDSA.RSAisthedefault.
ClickCreate PKI Profile.
206
Creating the PKI Profile Alias

PerformthefollowingproceduretocreateaPKIprofilealiasintheIntegrationServer. To create the PKI Profile Alias 1 2 3 4 5 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheAdaptersmenuoftheNavigationpanel,clickPKI. InthePKImenu,clickProfile Management. ClickCreate PKI Profile Alias. Updatethefollowingfields: Field PKI Profile Alias PKI Profile Location File System Contents AnaliasnameyouwanttoassociatewiththisPKI profile.Youcanspecifyanynameyouwant. SelectFileSystemorHardwareDevice,dependingon thelocationofthePKIprofile. File Name Nameofthe.epffilethatcontainsthePKIprofile.You canspecifyanabsoluteorrelativepath.Besureto specifyapaththatisvalidandaccessibletotheserver.If youspecifyjustthefilename,theserverlooksforthe PKIprofileontheserversrootdirectory. Label LabelofthetokentoassociatewiththisPKIprofile.To seealistoftokens(andtheirlabels)currentlyinserted intotheHSMdevice,clickView Label Information.Later, whenyouloginthePKIprofile,theserverwillsearch eachslotintheHSMdeviceuntilitfindsatokenwith thislabel. ACLthatgovernswhichusergroupsonyourservercan usethisPKIprofile.SelectanACLfromthedropdown list.Bydefault,onlymembersofgroupsgovernedby theInternalACLcanusethisprofile. AlistofexternalcertificatestrustedbythisPKIprofile. Youcanaddmultiplecertificatesbyusingthisformat: D:\certs\cert1;D:\certs\cert2;.... 6 ClickCreate PKI Profile Alias.
Hardware Device
Execute ACL
List of Trusted Certificates
207
Connecting to and Disconnecting from the PKI System

YoucanconnecttoanddisconnectyourIntegrationServerfromthePKIsystemas needed.TheIntegrationServermustbeconnectedtothePKIsystemforthefollowing tasks: CreatingaPKIprofile RecoveringaPKIprofile Performingkeyupdates To connect to and disconnecting from the PKI System 1 2 3 4 5 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheAdaptersmenuoftheNavigationpanel,clickPKI. InthePKImenu,clickPKI System Properties. ClickEditSystem Properties. IntheConnect to the PKI Systemfield,clickYestoconnect,orNotoDisconnect. Note: IftheIntegrationServerwillbedisconnectedfromthePKIsystemforalong time,besuretodisableCRLchecking.SeeAboutCRLCheckingonpage 217for moreinformation.
Logging in a PKI Profile

ForaPKIprofiletobeavailabletotheIntegrationServer(andthereforetoapplications thatrequireit),thePKIprofilemustbeloggedin.Forsecuritypurposes,asecurityofficer mustmanuallyloginthePKIprofile;theserverdoesnotautomaticallyperformthelogin duringserverinitialization.APKIprofileremainsloggedinuntilsomeonelogsitout, disablesorreloadstheWmPKIpackage,orshutsdowntheserver. Dependingonthecircumstances,youcanhaveoneormoreHSMstoredPKIprofiles loggedinatagiventimeandyoucanhave.epfandHSMstoredPKIprofilesloggedinat thesametime. Logging in a PKI Profile 1 2 3 IfyouarelogginginaPKIprofilethatisstoredonanHSMdevice,makesureyou inserttheappropriatetokenintoaslotontheHSMdevice. OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheAdaptersmenuoftheNavigationpanel,clickPKI.
208
4 5
InthePKImenu,clickProfile Management. IntheentryforthePKIprofileyouwanttologin,clickLog In.
Deleting a PKI Profile Alias

WhenyounolongerneedaPKIprofilealias,youcandeleteit.TheactualPKIprofilewill stillexist,buttheIntegrationServerwillnothaveaccesstoit.TodeletethePKIprofile completely,youcandeletethe.epffilefromthefilesystemor,ifyouuseanHSMdevice, useautilityprovidedbyyourvendortoerasethetoken. Deleting a PKI Profile 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheAdaptersmenuoftheNavigationpanel,clickPKI. InthePKImenu,clickProfile Management. Clickthe iconintheDeletefield.
Viewing and Updating Information for a PKI Profile

Youcandisplayand/orupdateinformationforaPKIprofile. To DeterminewhetheraPKIprofileisloggedin ChangethePKIprofilepassword Updatekeys Displayorupdatethetrustedcertificatelist DisplayorchangetheHSMtokenlabelnumberor.epffile DisplayorupdatetheExecuteACLassociatedwiththePKIprofile See page 211 213 214 210 210 210
209
Viewing or Updating PKI Profile Alias Information

To view or update Information for a PKI Profile Alias 1 2 3 4 5 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheAdaptersmenuoftheNavigationpanel,clickPKI. InthePKImenu,clickProfile Management. Clickthealiasname. Viewand/orupdatethefollowingfields: Field PKI Profile Alias PKI Profile Location Contents ThealiasnameassociatedwiththePKIprofile.(viewonly) File Name (IfthePKIprofileisstoredinyourfilesystem) Nameofthe.epffilethatcontainsthePKIprofile.Thisfilemust havebeenpreviouslycreated.Youcanspecifyanabsoluteor relativepath.Besuretospecifyapaththatisvalidand accessibletotheserver.Ifyouspecifyjustthefilename,the serverlooksforthePKIprofileintheserversrootdirectory. Label (IfthePKIprofileisstoredinyourHSMdevice) LabelofthetokenassociatedwiththisPKIprofile.Whenyou logintothePKIprofile,theserversearcheseachslotinthe HSMdeviceuntilitfindsatokenwiththislabel.Toviewthe Slot List NumberandSerial Numberforthelabel,clickView Label Information. Execute ACL ACLthatgovernswhichusergroupsonyourservercanuse thisaliasforthePKIprofile.SelectanACLfromthedropdown list.Bydefault,onlymembersofgroupsgovernedbythe InternalACLcanusethisalias. AlistofexternalcertificatestrustedbythisPKIprofile.Youcan addmultiplecertificatesbyusingthisformat: D:\certs\cert1;D:\certs\cert2;....
List of Trusted Certificates
210
Determining Whether a PKI Profile Is Logged In

APKIprofilemustbeloggedinforyoutocreateorrecoveraPKIprofileortoupdate keys.TodeterminewhetheraPKIprofileisloggedin,dothefollowing: Important! APKIprofileisassociatedwithauserthatyouhadaRegistrationAuthority create.Ifyouusedmultibytecharacterswhensupplyinginformationfortheuser,you cannotrecoverthePKIprofile.Multibytecharactersarenotsupported. To determine whether or not a PKI profile is logged in 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheAdaptersmenuoftheNavigationpanel,clickPKI. InthePKImenu,clickProfile Management. LookattheLogged IncolumnforthePKIprofile.IfitcontainsYes,theprofileislogged in.IfitcontainsNo,theprofileisloggedout.
Recovering a PKI Profile

IfaPKIprofileislost,revoked,oraccidentallydeleted,youcanrecoveritusingthe recoveryfacility.Oncerecovered,thePKIprofilehasanewsetofencryptionandsigning keypairs.Theserverretrievesyourolddecryptionkeys.Beforeyoucanrecoveraprofile, youmustobtainareplacementReferenceNumberandAuthorizationCodefromyour RegistrationAuthority. Important! YourservermustbeconnectedtoyourPKIsystemwhenyourecoveraPKI profile. To recover a PKI Profile 1 IfyouarerecoveringaPKIprofilethatisstoredonanHSMdevice,makesurea preformattedtokenhasalreadybeeninsertedintoaslotinthedevice.Thetoken shouldbeemptyexceptforalabelandapassword.ClickView Label Informationto displayalistoftokens(andtheirlabels)currentlyinsertedintheHSMdevice. OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheAdaptersmenuoftheNavigationpanel,clickPKI. InthePKImenu,clickProfile Management. ClickRecover PKI Profile.
2 3 4 5
211
Updatethefollowingfields: Field Activation Codes from Registration Authority Contents Reference Number Referencenumberprovidedbyyourregistrationauthority whenyouinitiatedthekeyrecovery. Authorization Code Authorizationcodeprovidedbyyourregistrationauthority whenyouinitiatedthekeyrecovery. PKI Profile Location File System Enterinformationinthesefieldsonlyifyouwanttostorethe PKIprofileinyourfilesystem. File Name Nameofthe.epffile.Youcanspecifyanabsoluteorrelative path.Ifyouspecifyjustthefilename,theserverwritesthePKI profiletotheserversrootdirectory.Besuretospecifyapath thatisvalidandaccessibletotheserver. Password PasswordyouwanttoassociatewiththePKIprofile. Confirm Password Enterthesamepasswordagaintomakesureyoutypedit correctly. Hardware Device Enterinformationinthesefieldsonlyifyouwanttostorethe PKIprofileonanHSMdevice. Label LabelofthetokentoassociatewiththisPKIprofile.Toseealist oftokens(andtheirlabels)currentlyinsertedintotheHSM device,clickView Label Information.Later,whenyouloginthePKI profile,theserverwillsearcheachslotintheHSMdeviceuntilit findsatokenwiththislabel. Password PasswordassociatedwiththePKIprofile.Thispasswordwas assignedtothetokenwhenitwasformatted. Use Auxiliary Profile CreatesanauxiliaryPKIprofile,whichstoresinformationabout previousdecryptionkeyupdates.Theserverusesthisfilewhen decryptingmessagesthatwereencryptedwithanoldkey.
212
Field
Contents Path to Auxiliary Profile PathtotheauxiliaryfilefortheHSMdevice(seebelow).Besure tospecifyapaththatisvalidandaccessibletotheserver. Auxiliary Profile Name NameoftheauxiliaryfilefortheHSMdevice.Thisfileresides onthefilesystemandcontainsahistoryofalldecryptionkeys created.Whenyouperformakeyupdate,thenewdecryption keyisaddedtothefile.Theserverusesthisfilewhendecrypting messagesthatwereencryptedwithanoldkey.
Key Information
Key Strength Strengthofthesigningandencryptionkeys,measuredasthe numberofbitsinthekey.Select1024or2048.1024isthedefault. Alargersizeincreasesthestrengthofencryption,butcanslow performance. Key Pair Algorithm Encryptionalgorithmtouseforthesigningandencryptionof keys.SelectRSAorDSA.RSAisthedefault.
ClickRecover PKI Profile.
Changing the Password for a PKI Profile

PasswordsarerequiredtologintoPKIprofiles.YoucanchangethepasswordforaPKI profile.TheremaybetimeswhentheserverasksyoutochangeaPKIprofilepassword. SeePasswordRulesonpage 217formoreinformation. Note: IfyouareusingannCipherHSMdevice,youcannotchangethepasswordusing thismethod.Usethevendorutilityinstead To change a password 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheAdaptersmenuoftheNavigationpanel,clickPKI. InthePKImenu,clickProfile Management.
IntheChange PasswordcolumninthePKIProfileAliasList,clickPassword intherowfor thePKIprofilewhosepasswordyouwanttochange.Theserverpromptsyoutoenterthe newpasswordandconfirmit.
213
Important! Theprofilepasswordcanonlybechangediftheprofilealiasisloggedin (i.e.iftheLogged InfieldissettoYes).IftheprofileshowsDisabledintheChange Passwordcolumn,gototheLogged IncolumnandclickLog In.
Updating Keys
Forsecuritypurposes,keyshaveexpirationdates.Thispreventsunlimiteduseincases whereCRLsarenotbeingchecked.Whenandhowkeysexpiredependsonthekindof keyaccountyousetupwithyourPKIauthority.Thereareusuallytwokindsofaccounts: WithExpiry Accounts,thekeyexpiresonaspecificdateandisnotrenewable.Youmight obtainanexpirykeyaccountforacontractorwhoworksforyourcompanyfor6months. Youcannotupdatekeysforexpiryaccounts. WithaRenewal Account,thekeywillexpire,butyouhavetheoptionofrenewingit.The PKIauthoritycanrenewitforyouautomatically,oryoucanrenewitmanually.ThePKI authoritywillattempttoautomaticallyrenewthekeyafteraperiodoftime,forexample, 6months.Ifyouwanttorenewthekeybeforethen,youcandosofromtheIntegration ServerAdministrator. Whenyoureneworupdateakey,theserverobtainsanewkeyfromyourPKIsystemand writesittothePKIprofile. Important! YourservermustbeconnectedtoyourPKIsystemwhenyouupdatekeys. To update keys 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheAdaptersmenuoftheNavigationpanel,clickPKI. InthePKImenu,clickProfile Management. IntheUpdate KeyscolumninthePKIProfileList,clickUpdate intherowforthePKI profilewhosekeysyouwanttoupdate. Important! Thekeyscanonlybeupdatediftheprofileisloggedin(i.e.,iftheLogged InfieldissettoYes.IftheLogged InfieldissettoNo,thenclickLog In.
214
Exporting a PKI Profile from the File System to an HSM Device

YoucanstorePKIprofilesinthefilesystem(as.epffiles)oronanHSMdevice.Ifyour PKIprofilesarestoredinthefilesystem,butyouwantthegreatersecurityofanHSM device,youcanexportthePKIprofilestoanHSMdevice. Beforebeginning,youmusthaveinstalledanHSMdevice(accordingtothe manufacturersinstructions)andconnectedittothemachineonwhichyourIntegration Serverruns. Afteryouhaveexportedtheprofile,youmustcreateanewaliasforit.SeeCreatingthe PKIProfileAliasonpage 207forinstructions. To export a PKI Profile 1 Makesureyouhavealreadyinsertedapreformattedtokenintoaslotinthedevice. Thetokenshouldbeemptyexceptforalabelandapassword.ClickView Label Informationtodisplayalistoftokens(andtheirlabels)currentlyinsertedintheHSM device. OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheAdaptersmenuoftheNavigationpanel,clickPKI. InthePKImenu,clickProfile Management. ClickExport PKI Profile from File System to Hardware Device. Enterinformationinthefollowingfields: Field PKI Profile on File System Contents File Name Nameofthe.epffilethatcontainsthePKIprofile.Youcan specifyarelativeorabsolutepath.Besuretospecifyapaththat isvalidandaccessibletotheserver.Ifyouspecifyjustafile name,theserverlooksforthefileintheserverrootdirectory. Label LabelofthetokentoassociatewiththisPKIprofile.Toseealist oftokens(andtheirlabels)currentlyinsertedintotheHSM device,clickView Label Information.Later,whenyouloginthePKI profile,theserverwillsearcheachslotintheHSMdeviceuntilit findsatokenwiththislabel. Export Key History WhetherornotyouwantthePKIprofileskeyhistorytobe exportedwiththePKIprofile.Thekeyhistorywillbewrittento thenewPKIprofileontheHSMdevice.
2 3 4 5 6
PKI Profile on Hardware Device
215
Field
Contents Use Auxiliary Profile CreatesanauxiliaryPKIprofile,whichstoresinformationabout previousdecryptionkeyupdates.Theserverusesthisfilewhen decryptingmessagesthatwereencryptedwithanoldkey. Path to Auxiliary Profile PathtotheauxiliaryPKIprofilefortheHSMdevice(seebelow). Besuretospecifyapaththatisvalidandaccessibletotheserver. Auxiliary Profile Name NameoftheauxiliaryfilefortheHSMdevice.Thisfileresidesin thefilesystemandcontainsahistoryofalldecryptionkeys created.Whenyouperformakeyupdate,thenewdecryption keyisaddedtothefile.Theserverusesthisfilewhendecrypting messagesthatwereencryptedwithanoldkey.
Password for PKI Profile 7
Password PasswordassociatedwiththePKIprofile.Thispasswordis requiredwhenyouloginthePKIprofile.
Createanewaliasfortheprofile.SeeCreatingthePKIProfileAliasonpage 207for instructions.
Installing an Entrust PKI Proxy

IfyourPKIadministratordoesnotallowdirectconnectionstoyourPKIsystem,youcan setupanEntrustPKIproxy.Theproxysitsbetweentheclient(inthiscaseyour webMethodsIntegrationServer)andyourPKIsystemandroutesPKIXCMPmessages betweenthem.Tosetuptheproxy: 1 2 Installawebserverthatcanhostservlets. Onthisserver,installtwoservletsprovidedbyEntrust. TheManager servletdirectsmessagestothePKICertificateAuthority. TheDirectory servletdirectsmessagestotheLDAPdirectory. 3 ConfigureyourIntegrationServertopointtotheproxyserver.SeeConfiguringPKI SystemSettingsonpage 202forinstructions.
216
Password Rules
Undersomecircumstances,theIntegrationServermightaskyoutochangeaPKI profilespassword.ThiscanhappenifyoutrytologinaPKIprofilewhenyour IntegrationServerisnotconnectedtothePKIsystem. WhentheIntegrationServerisconnectedtothePKIsystem,theIntegrationServer followsthePKIsystemsrulesforpasswords.(ThePKIsystemsrulesareenforcedwhen youcreateapasswordbecausetheIntegrationServermustbeconnectedtothePKI systemforPKIprofilecreation.)WhentheIntegrationServerisnotconnectedtothePKI system,theserverusesadefaultsetofpasswordrules.Thesedefaultrulesarestoredin yourIntegrationServer. IfyouloginaprofilewhenyourIntegrationServerisnotconnectedtoyourPKIsystem (whentheserversdefaultrulesareineffect)andyourdefaultrulesaremorerestrictive thantherulesunderwhichthePKIprofilewascreated(thePKIsystemsrules),the IntegrationServerwillloginthePKIprofilethenaskyoutochangethepasswordtoone thatadherestothedefaultrules. Example: YourPKIsystemrulesandthedefaultrulesarethesameexceptyourdefaultrules requirethatapasswordcontainadigit.TheFinancePKIprofilespassworddoesnot containadigitbecauseonewasnotrequiredduringcreation.Youtrytologinthe FinanceprofilewhentheIntegrationServerisnotconnectedtothePKIsystem.The IntegrationServer(runningwiththedefaultrules)seesthatthepassworddoesnot containadigitandasksyoutochangethepassword.Afteryouchangethepasswordto onethatadherestothedefaultrules,thatis,containsadigit,theIntegrationServerallows youtologintheFinancePKIprofile.
About CRL Checking

ACRL(CertificateRevocationList)isalistofcertificatesthathavebeenrevokedbya CertificateAuthority.Revokedcertificatesarenolongervalid.Byhavingyourserver performCRLchecking,youavoidacceptingacertificatethathasbeencompromised. TheCertificateAuthoritymaintainsthislistandupdatesitperiodically.(Somecertificate authoritiessendnotificationseverytimetheyrevokeacertificate.)TheCRLisstoredin thePKIsystemsLDAPdirectory. CRLcheckingisperformedonlyforinternalcertificates,thatis,certificatesissuedby yourPKIsystemscertificateauthority. Bydefault,theserverdoesnotperformCRLchecking.YoucanturnCRLcheckingonor offasneeded.
217
IfCRLcheckingisturnedon,theIntegrationServerperformsitatthefollowingtimes: WhenyouloginaPKIprofile. IfCRLcheckingisenabledandtheserverencountersarevokedcertificate,theserver rejectsthecertificate(andtherequest)andissuesanerrormessage.

Could not login PKI Profile Alias 'alias': The signing certificate is not valid: The certificate being validated is revoked.
Duringsignatureverification. Theserverperformssignatureverificationwhenitprocessesasigneddocument.If theclientscertificatewassignedbyyourCA,theserverperformsarevocationcheck atthispoint. Note: IfyourserverwillbedisconnectedfromthePKIsystemforlongperiodsoftime, disableCRLchecking.
How Often Is the CRL Downloaded?

TheserverdoesnotdownloadCRLsaspartofserverstartup.Rather,theserver downloadsaCRLonlywhenitisneeded.Forexample,thefirsttimeauserlogsinaPKI profileafterserverstartup,theserverdownloadstheCRLassociatedwiththatPKI profile.TheCRLisstoredintheserversmemory.IfanotheruserlogsinaPKIprofilethat requiresthesameCRL,theserverusesthesamecopyoftheCRLalreadyintheservers memory.TheserverdoesnotrefreshthatcopyuntiltheCRLhasbeenintheservers memoryforalengthoftimethatexceedsalimitthatyourPKIadministratorsets.The defaultis24hours.ThismeansthataCRLintheserverscachecanbecomeoutofsync withthemasterCRLmaintainedbythecertificateauthority.
218
15
Setting Up a Reverse HTTP Gateway

220 221 222 222 223 233 237 238
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How Reverse HTTP Gateway Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Advantages to Reverse HTTP Gateway vs. Traditional Third-Party Proxy Servers . . . . . . . . . . . Clustering in the Reverse HTTP Gateway Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up the Reverse HTTP Gateway Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Connecting Your Internal Server to a Reverse HTTP Gateway Server . . . . . . . . . . . . . . . . . . . . Performing Client Authentication on the Reverse HTTP Gateway Server . . . . . . . . . . . . . . . . . . Frequently Asked Questions About Reverse HTTP Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . .
219
15 Setting Up a Reverse HTTP Gateway
Overview
IfyourIntegrationServersitsbehindaninternalfirewallandisnotallowedtoaccept communicationsfromexternalclientsthroughtheDMZ,youcansetupaReverseHTTP GatewaytoallowtheInternalServertoprocessrequestsfromexternalclients. Inthisconfiguration,yourInternalServersremainbehindyourinnerfirewall,where externalclientscannotaccessthem.YouplaceanotherIntegrationServerinyourDMZto actasaReverseHTTPGatewayServer.TheReverseHTTPGatewayServeractsasan intermediarybetweentheInternetandyourInternalServers. Bydefault,alluservalidationandtransactionprocessingisperformedontheInternal Server.
Internet 1 External Client 4 Outer Firewall Reverse HTTP Gateway Server DMZ 2 Internal Server 3 Inner Firewall Pre-existing persistent connection established by Internal Server Internal Network
ExternalclientssendrequeststotheReverseHTTPGatewayServer(1),whichinturn passestherequeststotheInternalServer(2).Afterprocessingtherequests,theInternal ServersendstheresponsetotheReverseHTTPGatewayServer(3),whichinturnpasses itbacktotheclient(4). WithaReverseHTTPGateway,thereisnoneedtoopenaportthroughtheinternal firewalltoallowaconnectionfromtheDMZtotheinternalnetwork. ForaReverseHTTPGatewaytowork,theinternalfirewallmuststillallowaconnection fromtheInternalServertotheDMZ(thatis,anoutboundconnection).Bylimitingthe connectionstojustthoseestablishedbytheInternalServer,theReverseHTTPGateway facilitymakesitmoredifficultforanattackertodirectlypenetrateyourinternalnetwork, eveniftheysubvertasystemintheDMZ.However,likeanyothersecuritymechanism,it isnotfoolproof;theinformationstillflowsfromtheDMZtotheinternalnetworkover theconnectionestablishedfromtheinside. TheReverseHTTPGatewayServeristransparenttotheclientand,unlikesomethird partyproxyservers,requiresnomodificationstotheclient.
220
ReverseHTTPGatewaysupportsnearlyallrequeststhataregularIntegrationServer handles,includingguaranteeddelivery. Important! TogetthemaximumbenefitfromtheReverseHTTPGateway configuration,Software AGhighlyrecommendsthatyouconfigureyourinner firewalltodenyallinboundconnections.
How Reverse HTTP Gateway Works

ForanIntegrationServertofunctionasaReverseHTTPGatewayServer,itmusthavea gatewayexternalporttolistenforrequestsfromexternalclients(partners)andagateway registrationportthroughwhichitmaintainsitsconnectiontotheInternalServer.For securitypurposes,theInternalServerinitiatestheconnectionstotheReverseHTTP GatewayServersregistrationport. ThefollowingstepssummarizehowanexternalclientrequestishandledinaReverse HTTPGatewayscenario: TheexternalclientsendsarequesttotheReverseHTTPGatewayServer. TheReverseHTTPGatewayServerstreamsthemessagebetweentheinbound connectionandtheoutboundconnectiontotheInternalServer. TheInternalServerprocessestherequestthensendsaresponsetotheReverseHTTP GatewayServer. TheReverseHTTPGatewayServersendsaresponsetotheexternalclient. Thefollowingdiagramshowsthelocationofthegatewayexternalportandgateway registrationportintheReverseHTTPGatewayconfiguration.
Internet DMZ Reverse HTTP Gateway Server External Client Gateway External Port Gateway Registration Port Internal Network Internal Server
External Client
Persistent connections established by Internal Server
221
Advantages to Reverse HTTP Gateway vs. Traditional ThirdParty Proxy Servers

AReverseHTTPGatewayconfigurationoffersanumberofadvantagesovertraditional thirdpartyproxyservers: ReverseHTTPGatewayusespersistentconnections.Theseconnectionseliminatethe hugeoverheadofestablishingSSLconnections,whileprovidingallthebenefitsof encryption. WithReverseHTTPGateway,youcanconfigureyourinnerfirewalltodenyall inboundconnections,isolatingtheInternalServerfromtheDMZ. ReverseHTTPGatewayrequiresnochangestotheexternalclient. AReverseHTTPGatewayServercanhandlebothHTTPandHTTPSrequests. Typicallythirdpartyproxyserverscanhandleonlyoneortheother.
Clustering in the Reverse HTTP Gateway Configuration

YoucanhavemultipleReverseGatewayIntegrationServersanduseathirdparty producttoloadbalancethem.Inaddition,youcanclusteryourinternalIntegration Serverstoimproveavailability,reliability,andscalability.Formoreinformationabout IntegrationServerclustering,refertothewebMethodsIntegrationServerClusteringGuide. Thediagrambelowillustratesasupportedconfiguration.Keepthefollowingpointsin mindwhenworkingwithclusteredinternalIntegrationServers: EachinternalIntegrationServermustconnecttoeachReverseGatewayIntegration Server. DonotcreateaclusterofReverseGatewayserversorincludethemasmembersofa clusterofregularIntegrationServers.
Internet DMZ Internal Network
External Client 3rd-Party Load Balancer External Client
Reverse Gateway Integration Server
Internal Integration Server
Reverse Gateway Integration Server
Internal Integration Server
Cluster of Internal Integration Servers
222
Setting Up the Reverse HTTP Gateway Server

ThetwomainstepstosettingupaReverseHTTPGatewayconfigurationare: ConfiguringanIntegrationServerintheDMZtobeaReverseHTTPGatewayServer ConfiguringyourInternalIntegrationServertoconnecttotheReverseHTTP GatewayServer. ThissectiondescribeshowtosetuptheReverseHTTPGatewayServer. ForinstructionsonsettingupyourInternalServer,seeConnectingYourInternalServer toaReverseHTTPGatewayServeronpage 233. Important! DonotconfigureasingleIntegrationServertobebothaReverseHTTP GatewayServerandanInternalServer.Thisconfigurationisnotsupported,and unpredictableresultswilloccur. ThefollowingchecklistsummarizesthetasksinvolvedinsettingupaReverseHTTP GatewayServer: Task Installan IntegrationServer inyourDMZtobe yourReverseHTTP GatewayServer Notes Installtheserverandfollowtheinstructionsbelow. AnyexternalclientontheInternetcanaccessyourReverse HTTPGatewayServer;therefore,beverysecurity consciousabouttheservicesyoumakeavailableandthe usersyoudefine. Donotperformdevelopmentworkinthisserveranddo notsetupusersorgroupsonit. Disablethe Developerand Replicatorusers YouwillnotneedtheseusersonaReverseHTTPGateway Server.Disablingtheseuserspreventssomeonefrom gainingaccesstoyourReverseHTTPGatewayServer throughthem.SeeDisablingandEnablingUserson page 52. ThisistheportthroughwhichtheReverseGateway IntegrationServerlistensforrequestsfromexternal clients.AnIntegrationServerisnotconsideredtobea ReverseGatewayIntegrationServerunlessithasan enabledgatewayexternalport.Configureaccesstothis portsothatpartnersandotherclientswithwhomyou tradehaveaccess. Note: IfyouplantouseanHTTPSporthere,youmust storeaservercertificate,serverprivatekey,andaCA certificateonthisserver.SeeChapter 11,Securing CommunicationswiththeServerforinstructions.
Setupthegateway externalport
223
Task Setupthegateway registrationport
Notes ThisistheportthroughwhichtheReverseGateway IntegrationServermaintainsitsconnectiontotheInternal Server.SeeSettingUptheGatewayExternalPorton page 224forinstructionsonsettingupthisport. Ifyouaregoingtosetupanencryptedconnection betweentheInternalServerandtheReverseGateway IntegrationServer,youcanoptionallystoreacertificatefor theInternalServersadministratoruserontheReverse GatewayIntegrationServer.SeeImportingaClient CertificateandMappingIttoaUseronpage 186formore information. Optional(butstronglyrecommended).SetupIPaddress filteringontheregistrationportsothatonlytheInternal IntegrationServercanconnecttoyourReverseGateway IntegrationServer.Thisstepprovidesanadditionallayer ofprotectiontosupplementtheIPaddressfiltering performedbyyourfirewallandtheuserauthentication. Note: Evenifyourexternalfirewallfiltersoutconnections totheReverseGatewayregistrationport,IPaddress filteringisagoodideabecauseitwillstopinsidersfrom connectingtotheReverseGatewayIntegrationServer. SeeRestrictingIPAddressesthatCanConnecttoaPort onpage 159formoreinformation.
Setting Up the Gateway External Port

ThisproceduredescribeshowtosetupagatewayexternalportonyourReverseHTTP GatewayServer.ThegatewayexternalportistheportthroughwhichtheReverseHTTP GatewayServerlistensforrequestsfromexternalclients.AnIntegrationServerisnot consideredtobeaReverseHTTPGatewayServerunlessithasanenabledexternal gatewayport.
gateway external port
external client
Gateway Server
Internal Server
Note: Bydefault,thisportwillbedisabledandallserviceswillbesettodenyby defaultexceptforsomebasicservicesrequiredbytheIntegrationServer.
224
To set up the gateway external port 1 2 3 4 5 OpentheIntegrationServerAdministratorfortheReverseHTTPGatewayServerifit isnotalreadyopen. IntheNavigationpanelofthescreen,ontheSecuritymenu,clickPorts. UnderAdd Port,selectReverseHTTP Gateway Server. ClickSubmit. OntheEdit ReverseHTTP Gateway Server Configurationscreen,intheGateway External Port Portpanel,enterthefollowinginformation: For this parameter Specify... Protocol Port SelectHTTPorHTTPS.IfyouselectHTTPS,additionalsecurity andcredentialfieldswillbedisplayedatthebottomofthescreen. Thenumberyouwanttouseforthegatewayexternalport.Usea numberthatisnotalreadyinuse.Thisistheportthatclientswill connecttothroughyourouterfirewall. Thisfieldassociatesapackagewithaport.Typicallyyouwillnot needtoworkwithpackagesonaReverseHTTPGatewayServer; therefore,youcanleavethisfieldwiththedefaultsetting. IPaddresstowhichtobindthisport.Specifyabindaddressif yourmachinehasmultipleIPaddressesandyouwanttheportto usethisspecificaddress.Ifyoudonotspecifyabindaddress,the serverpicksoneforyou. Howlongarequestwillremaininthequeueaftertheportis suspended.Thedefaultis200milliseconds(ms).Themaximumis 65535ms.Afterthistimehaspassed,therequestisrejected.
Package name
Bind Address (optional)
Backlog
Keep Alive Timeout Howlongtowaitbeforeclosinganidleconnectiontoaclient.The defaultis20000ms. Threadpool IfyouselectDisable,theserverusesthecommonserverthread poolforthisport. IfyouselectEnable,theservercreatesaprivatethreadpoolfor thisportsothatitdoesnotneedtocompetewithotherserver functionsforthreads.IfThreadpoolisenabled,thefollowingthree fieldsaredisplayed. Threadpool Min Minimumnumberofthreadstheservermaintainsinthisthread pool.WhentheReverseGatewayServerstarts,thethreadpool initiallycontainsthisminimumnumberofthreads.Theserver addsthreadstothepoolasneededuntilitreachesthemaximum allowed.Thedefaultis1.
225
For this parameter Specify... Threadpool Max Maximumnumberofthreadstheservermaintainsinthisthread pool.Ifthismaximumnumberisreached,theserverwaitsuntil servicescompleteandreturnthreadstothepoolbeforerunning moreservices.Thedefaultis5. Threadpool Priority PrioritywithwhichtheJVMtreatsthreadsfromthisthreadpool. Thelargerthenumber,thehigherthepriority.Thedefaultis5. Important! Beverycarefulwhensettingthethreadpoolpriority;it canaffectserverperformanceandthroughput. IfyouselectedHTTPSintheProtocolfield,enterthefollowinginformationinthe Security Configurationpanel: For this parameter Specify Client Authentication Thetypeofclientauthenticationtoperformforrequestscoming throughthegatewayexternalport(inotherwords,requests comingfromtheexternalclient).SeeChapter 13,Authenticating Clientsformoreinformation. Note: InadefaultReverseHTTPGatewayconfiguration,the ReverseHTTPGatewayServerdoesnotperformclient authentication.Rather,itobtainsauthenticationinformation (user/passwordorcertificates)fromtheexternalclientandpasses ittotheInternalServerforauthentication.However,ifyouwant theReverseHTTPGatewayServertoperformclient authenticationaswell,youcandosobysettingthe watt.server.revInvoke.proxyMapUserCertssystempropertyto true.SeePerformingClientAuthenticationontheReverse HTTPGatewayServeronpage 237formoreinformation. Username/Password.TheReverseHTTPGatewayServerwillnot requestclientcertificates.Insteaditlooksforuserandpassword informationintherequestheader. Request Client Certificates.TheReverseHTTPGatewayIntegration Serverwillrequestclientcertificatesforrequeststhatcome throughthisport(thegatewayexternalport).Iftheclientdoes notpresentacertificate,therequestproceedsusingtheuserand passwordinformationcontainedintherequestheader.
226
For this parameter Specify Require Client Certificates.TheReverseHTTPGatewayServer requiresclientcertificatesforallrequeststhatcomethroughthis port(thegatewayexternalport).Iftheclientdoesnotsupplya certificate,therequestfails. Important! Usethesameauthenticationmodehereasyouusefor theInternalServer.Forexample,supposeyouspecify authenticationmodeRequiredontheInternalServer.Specifying RequiredonthegatewayexternalportoftheReverseGateway IntegrationServerensuresthattherequestpassedtotheInternal Serverincludesacertificate. IfyouselectedHTTPSintheProtocolfield,optionallyenterthefollowinginformation intheListener Specific Credentialspanel: For this parameter Specify Servers Certificate Optional.Pathandfilenameofthefilethatcontainsthedigital certificatethattheReverseGatewayIntegrationServeristo presenttorequestscominginthroughthisport(thegateway externalport). Specifyavaluehereonlyifyouwantthisporttopresenta differentservercertificatefromtheonespecifiedonthe Certificatesscreen. Authoritys Certificate Optional.Pathandfilenameofthefilethatcontainsthe certificateforthecertificateauthoritythatsignedthedigital certificatespecifiedintheServers Certificate field. Ifyouleavethisfieldblank,theReverseGatewayIntegration ServerusesthefilespecifiedontheCertificatesscreen. Private Key Optional.Pathandfilenameofthefilethatcontainstheprivate keyoftheprivate/publickeypairassociatedwiththedigital certificatespecifiedintheServers Certificate field. Ifyouleavethisfieldblank,theReverseGatewayIntegration ServerusestheprivatekeyspecifiedontheCertificatesscreen.
227
For this parameter Specify Trusted Authorities Optional.Nameofthedirectory(absoluteorrelative)that Directory containsthedigitalcertificatesofcertificateauthoritiestrustedby thisserver,forexampleconfig\cas. Iftheexternalserverpresentsaclientcertificate,theReverse HTTPGatewayServerlooksinthisdirectorytoseeiftheclient certificatewassignedbyanauthoritytheReverseHTTPGateway Servertrusts. Ifyouleavethisfieldblank,theReverseHTTPGatewayServer usesthetrustedauthoritydirectoryspecifiedontheCertificates screen.IfthetrustedauthorityfieldisblankontheCertificates screenaswell,theReverseHTTPGatewayServertrustsno certificates. ---Or--KeyStore Location Optional.Thelocationondiskwherethekeystoreislocated(for anHSM/smartcardbackedkeystore,afileexistsondiskbutdoes notcontaintheactualprivatekey). KeyStore Password Optional.Thepasswordwithwhichthekeystoreisprotected.If theprivatekeyandcertificatechainarestoredonanHSMdevice, thispropertymustmatchthepasswordwithwhichthecardwas protected(forexample,fornCipherastheHSMprovider,this propertymustmatchtheOCS(OperatorCardSet)passwordfor thecard). Optional.Thetypeofthekeystore.Differentvendorssupport differenttypesofkeystore;forexample,thedefaultSUNkeystore implementationisoftypejks(nCipheralsousesthistype). Withinthisproperty,thenameinparenthesesisthenameofthe SecurityProviderthatwillprovidesupportforthekeystore type.Ifthedesiredproviderisnotlistedinthedropdownlist, youcanadditbyclickingtheAddnewSecurityProviderlink. Formoreinformationabouthowtoaddasecurityprovider,see AddingaSecurityProvideronpage 114. Aslongasaportwiththegivenproviderexists,youwillnot havetomanuallyreregisterthesecurityprovider.Ifthelastport whichusesthisproviderisdeletedandtheIntegrationServeris restarted,youmustreregisterthissecurityproviderbefore usingitforaport. Important! IntegrationServersupportsJKSandPKCS#12keystore typesonly.OtherkeystoretypesmayworkwithIntegration Serverbutarenotsupported.
KeyStore Type
228
For this parameter Specify HSM Based Keystore Optional.Indicateswhetherornotthekeystoreisbackedbyan HSMbasedkeystore(asmartcarddevicecanbeusedaswell). Whenthekeystoreisbackedbysuchadevice,theprivatekey doesnotphysicallyleavetheHSMdeviceandcertain cryptographicoperationsmustbeperformedonthatdevice. RequirediftheKeyStore Locationparameterisdefined.Ifthe KeyStore Locationparameterisnull,theAliaspropertyisignored. Specifiesthealiasthatpointstotheprivatekeyanditsassociated certificatechaininthekeystore.Eachlistenerpointstoonealias onthekeystore;therecanbemultiplealiasesinthesamekeystore andmorethanonelistenercanusethesamealias. Trusted Authority Directory Optional.Specifiesthenameofthedirectorythatcontainsthe certificatesofthecertificationauthorities(CAs)thatthisserver trustswhenitusesthisport;forexample, config\xApps\TrustedCAs. Note: Currentlythekeystorestoresonlytheprivatekeyandits associatedcertificatechain,notthetrustedCAcertificates. 6 7 ClickSave Changes. LocatetheportinthePort List,andclickNointheEnabledcolumntoenablethe gatewayexternalport.Theserverdisplaysadialogboxthatpromptsyoutoverify youraction.ClickOKtoverifyyouwanttoenabletheport. TheserverreplacestheNo withthe icontoindicatethattheportisnowenabled.
Alias
229
Setting Up the Gateway Registration Port

ThissectionexplainshowtosetupthegatewayregistrationportonaReverseHTTP GatewayServer.ThegatewayregistrationportistheportthroughwhichtheReverse HTTPGatewayServermaintainsitsconnectiontotheInternalServer.
gateway registration port
external client
Gateway Server
Internal Server
To set up the gateway registration port 1 2 3 4 5 OpentheIntegrationServerAdministratorfortheReverseGatewayIntegration Serverifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickPorts. UnderAdd Port,selectReverseHTTP Gateway Server. ClickSubmit. OntheEdit ReverseHTTP Gateway Server Configurationscreen,intheGateway Registration Portpanel,enterthefollowinginformation: For this parameter Protocol Specify SelectHTTPorHTTPS.IfyouselectHTTPS,additional securityandcredentialfieldswillbedisplayedatthebottom ofthescreen. Thenumberyouwanttouseforthegatewayregistrationport. Useanumberthatisnotalreadyinuse. Itisbestnottouseastandardportsuchas80(thestandard portforHTTP)or443(thestandardportforHTTPS);sincethe externalfirewallwillallowaccesstothoseportsfromthe outsideworld. Package name Thisfieldassociatesapackagewithaport.Typicallyyouwill notneedtoworkwithpackagesfromaReverseGateway IntegrationServer;thereforeyoucanleavethisfieldwiththe defaultsetting.
Port
230
For this parameter Bind Address (optional)
Specify IPaddresstowhichtobindthisport.Specifyabindaddressif yourmachinehasmultipleIPaddressesandyouwanttheport tousethisspecificaddress.Ifyoudonotspecifyabind address,theserverpicksoneforyou. Howlongarequestwillremaininthequeueaftertheportis suspended.Thedefaultis200milliseconds(ms).The maximumis65535ms.Afterthistimehaspassed,therequest isrejected.
Backlog
IfyouselectedHTTPSintheProtocolfield,enterthefollowinginformationinthe Security Configurationpanel: For this parameter Client Authentication Specify ThetypeofclientauthenticationtoperformwhentheInternal ServerestablishesapersistentconnectiontotheReverse GatewayIntegrationServer.Thissettingcontrolswhetherthe ReverseHTTPGatewayServerwillasktheInternalServerto presentacertificate. SeeChapter 13,AuthenticatingClientsformoreinformation abouthowclientsareauthenticated. Username/Password.TheReverseHTTPGatewayServerwill notrequestaclientcertificatefromtheInternalServer,but ratherwilllookforuserandpasswordinformationinthe requestheader. Request Client Certificates.TheReverseHTTPGatewayServer willrequestaclientcertificatefromtheInternalServer.Ifthe InternalServerdoesnotpresentacertificate,therequest proceedsusingtheuserandpasswordinformationfromthe requestheader. Require Client Certificates.TheReverseHTTPGatewayServer requiresaclientcertificatefromtheInternalServer.Ifthe InternalServerdoesnotsupplyaclientcertificate,therequest fails.Inaddition,ifthecertificateisnotmappedtoauserwith AdministratorprivilegesontheReverseHTTPGateway Server,therequestfails.
231
IfyouselectedHTTPSintheProtocolfield,enterthefollowinginformationinthe Listener Specific Credentialspanel: For this parameter Servers Certificate Specify Optional.Pathandfilenameofthefilethatcontainsthe servercertificatefortheReverseHTTPGatewayServer.The ReverseHTTPGatewayServerpresentsthiscertificatetothe InternalServerfortheSSLhandshakewhentheInternal ServermakesitsinitialregistrationconnectiontotheReverse HTTPGatewayServer. Specifyavaluehereonlyifyouwantthisporttopresenta differentservercertificatefromtheonespecifiedonthe Certificates screen. Authoritys Certificate Optional.Pathandfilenameofthefilethatcontainsthe certificateforthecertificateauthoritythatsignedtheReverse HTTPGatewayServersdigitalcertificate. Ifyouleavethisfieldblank,theReverseHTTPGateway ServerusesthefilespecifiedontheCertificatesscreen. Private Key Optional.Pathandfilenameofthefilethatcontainsthe privatekeyoftheprivate/publickeypairassociatedwiththe digitalcertificatespecifiedintheServers Certificatefield, describedabove. Ifyouleavethisfieldblank,theReverseHTTPGateway ServerusestheprivatekeyspecifiedontheCertificatesscreen. Trusted Authorities Directory Optional.Nameofthedirectory(absoluteorrelative)that containsthedigitalcertificatesofcertificateauthoritiestrusted bythisserver,forexampleconfig\cas. IftheInternalServerpresentsaclientcertificate,theReverse HTTPGatewayServerlooksinthisdirectorytoseeiftheclient certificatewassignedbyanauthoritytheReverseHTTP GatewayServertrusts. Ifyouleavethisfieldblank,theReverseHTTPGateway Serverusesthetrustedauthoritydirectoryspecifiedonthe Certificatesscreen.IfthisfieldisblankontheCertificates screenaswell,theservertrustsnocertificates. 6 7 ClickSave Changes. LocatetheportinthePort List,andclickNointheEnabledcolumntoenablethe GatewayRegistrationport.Theserverdisplaysadialogboxthatpromptsyouto verifyyouraction.ClickOKtoverifyyouwanttoenabletheport. TheserverreplacestheNo withthe icontoindicatethattheportisnowenabled.
232
Connecting Your Internal Server to a Reverse HTTP Gateway Server

ThetwomainstepstosettingupaReverseHTTPGatewayconfigurationare: ConfiguringanIntegrationServerintheDMZtobeaReverseHTTPGateway IntegrationServer ConfiguringyourInternalServertoconnecttotheReverseHTTPGateway IntegrationServer ThissectiondescribeshowtosetuptheInternalServertoconnecttoaReverseHTTP GatewayServer.ForinstructionsonsettingupyourReverseHTTPGatewayServer,see SettingUptheReverseHTTPGatewayServeronpage 223.
Setting Up the Internal Registration Connections

ThisproceduredescribeshowtosetupanInternalServertoconnecttoaReverse GatewayServer.
registered connections
external client Gateway Server Internal Server
To set up the Internal Server 1 2 3 4 5 OpentheIntegrationServerAdministratorfortheInternalServerifitisnotalready open. IntheNavigationpanelofthescreen,ontheSecuritymenu,clickPorts. UnderAdd Port,selectInternal Server. ClickSubmit. OntheEdit Internal Server Configuration screen, intheInternal Serverpanel,enterthe followinginformation: For this parameter Protocol Specify SelectHTTPorHTTPS.IfyouselectHTTPS,additional securityandcredentialfieldswillbedisplayedatthebottom ofthescreen.
233
For this parameter Package name
Specify Thisfieldassociatesapackagewithaport.Typicallyyouwill notneedtoworkwithpackagesonanInternalServer; thereforeyoucanleavethisfieldwiththedefaultsetting. NumberofconnectionsmaintainedbetweentheReverse GatewayServerandtheInternalServer. IfyouselectDisable,theserverusesthecommonserverthread poolforthisport. IfyouselectEnable,theservercreatesaprivatethreadpoolfor thisportsothatitdoesnotneedtocompetewithotherserver functionsforthreads.IfThreadpoolisenabled,thefollowing threefieldsaredisplayed. Threadpool Min Minimumnumberofthreadstheservermaintainsinthis threadpool.Whentheserverstarts,thethreadpoolinitially containsthisminimumnumberofthreads.Theserveradds threadstothepoolasneededuntilitreachesthemaximum allowed.Thedefaultis1. Threadpool Max Maximumnumberofthreadstheservermaintainsinthis threadpool.Ifthismaximumnumberisreached,theserver waitsuntilservicescompleteandreturnthreadstothepool beforerunningmoreservices.Thedefaultis5. Threadpool Priority PrioritywithwhichtheJVMtreatsthreadsfromthisthread pool.Thelargerthenumber,thehigherthepriority.The defaultis5. Important! Beverycarefulwhensettingthethreadpool priority;itcanaffectserverperformanceandthroughput.
Max Connections Threadpool
IntheReverse HTTP Gateway Serverareaofthescreen,enterthefollowinginformation: For this parameter Host Port Specify HostnameorIPaddressofthemachineonwhichtheReverse HTTPGatewayServerisrunning. PortnumberofthegatewayregistrationportontheReverse GatewayServer.
IfyouselectedHTTPSintheProtocolfield,optionallyenterthefollowinginformation intheRegistration Credentialspanel.Notethattheregistrationcredentialsspecified
234
heremustsatisfythesettingsontheReverseHTTPGatewayServersGateway RegistrationPort: For this parameter User Name Password Servers Certificate Specify NameoftheuserontheReverseHTTPGatewayServerthat theInternalServershouldconnectas. PasswordoftheuserontheReverseHTTPGatewayServer thattheInternalServershouldconnectas. Optional.Pathandfilenameofthefilethatcontainsthedigital certificatethattheInternalServersendstotheReverseHTTP GatewayServerforclientauthentication.TheInternalServer sendsthiscertificatewhenitmakesitsinitialregistration connectiontotheReverseHTTPGatewayServer.TheInternal ServersendsthiscertificateonlyifaskedtobytheReverse HTTPGatewayServer. Specifyavaluehereonlyifyouwanttopresentadifferent servercertificatefromtheonespecifiedontheCertificates screen. Authoritys Certificate Optional.Pathandfilenameofthefilethatcontainsthe certificateforthecertificateauthoritythatsignedtheInternal Serversdigitalcertificate. Ifyouleavethisfieldblank,theInternalServerusesthefile specifiedontheCertificatesscreen. Private Key Optional.Pathandfilenameofthefilethatcontainsthe privatekeyoftheprivate/publickeypairassociatedwiththe digitalcertificatespecifiedintheServers Certificate field, describedabove. Ifyouleavethisfieldblank,theserverusestheprivatekey specifiedontheCertificatesscreen. Trusted Authority Directory Optional.Nameofthedirectory(eitherabsoluteorrelativeto theserverhome)thatcontainsthedigitalcertificatesof certificateauthoritiestrustedbythisserver,forexample config\cas. IftheReverseHTTPGatewayServerpresentsacertificate fromtheexternalclient,theInternalServerlooksinthis directorytoseeiftheexternalclientscertificatewassignedby anauthoritytheInternalServertrusts. Ifyouleavethisfieldblank,theInternalServerusesthe trustedauthoritydirectoryspecifiedontheCertificatesscreen. IfthisfieldisblankontheCertificatesscreenaswell,the servertrustsnocertificates.
235
IfyouselectedHTTPSintheProtocolfield,enterthefollowinginformationinthe External Client Securitypanel: For this parameter Client Authentication Specify ThetypeofclientauthenticationtheInternalServerperforms againstexternalclients.Externalclientspasstheir authenticationinformationtotheReverseHTTPGateway Server,whichinturnpassesittotheInternalServer.See Chapter 13,AuthenticatingClientsformoreinformation aboutprocessingclientcertificates. Username/Password.TheInternalServerwillnotrequestclient certificatesfromexternalclients.Insteaditwilllookforuser andpasswordinformationintherequestheader. Request Client Certificates.TheInternalServerwillrequestclient certificatesforrequestsfromexternalclients.Iftheexternal clientdoesnotpresentacertificate,therequestproceedsusing theuserandpasswordinformationcontainedintherequest header. Require Client Certificates.TheInternalServerrequiresclient certificatesforrequestsfromexternalclients.Iftheexternal clientdoesnotsupplyacertificate,therequestfails. Important! Usethesameauthenticationmodehereasyouuse forgatewayexternalport.Forexample,supposeyouspecify authenticationmodeRequiredontheInternalServer. SpecifyingRequiredonthegatewayexternalportofthe ReverseHTTPGatewayServerensuresthattherequestpassed totheInternalServerincludesacertificate. 6 7 ClickSave Changes. InthePort List,locateInternal Registration,andclickNointheEnabledcolumn.Thisstep enablestheconnectionbetweentheInternalServerandthegatewayregistrationport ontheGatewayHTTPServer.Theserverdisplaysadialogboxthatpromptsyouto verifyyouraction.ClickOKtoverifyyouwanttoenabletheconnection. TheserverreplacestheNo withthe enabled. icontoindicatethattheconnectionisnow
236
Performing Client Authentication on the Reverse HTTP Gateway Server

InadefaultReverseHTTPGatewayconfiguration,externalclientssendrequeststothe ReverseHTTPGatewayServer,whichresidesinyourDMZ.TheReverseHTTPGateway Serverforwardsauthenticationinformation(user/passwordorcertificates)aboutthese clientstotheInternalServer,whichperformstheauthentication.Thisisthe recommendedconfigurationbecausecertificatesaresaferwhenstoredontheInternal Server,behindtwofirewalls. However,ifyouwanttheReverseHTTPGatewayServertoperformclientauthentication inadditiontotheauthenticationperformedontheInternalServer,youcandoso.To enableclientauthenticationontheReverseHTTPGatewayServer,makethefollowing changes: 1 2 NavigatetotheSettings > Extendedscreenandsetthe watt.server.revInvoke.proxyMapUserCertssystempropertytotrue. IftheReverseHTTPGatewayServerisconfiguredtorequestorrequirecertificates, thenforeachexternalclienttowhichyouwanttoallowaccess,theReverseHTTP GatewayServermustcontaincopyoftheclientspubliccertificatemappedtoauser. Formoreinformationaboutmappingcertificates,seeImportingaClientCertificate andMappingIttoaUseronpage 186. If,instead,theReverseHTTPGatewayServerisconfiguredtorequestcertificatesor performauthenticationusingusernameandpassword,thentheReverseHTTP GatewayServermustcontainausernameforthatclient. Makesurethattheexternalclientsimportedcertficateorusernameisthesameon boththeReverseHTTPGatewayServerandtheInternalServer. 3 SettheclientauthenticationmodeofthegatewayexternalportontheReverseHTTP GatewayServertoRequire Client Certificates: a b c NavigatetotheSecurity > Portsscreen. Findtherowforthegatewayexternalportandclicktheportnumber,thenclick Edit HTTP Port Configuration. FromtheEdit Reverse HTTP Gateway Server Configuration screen,intheGateway ExternalPortareaofthescreen,intheClient Authenticationfield,selectRequire Client CertificatesandclickSave Changes.
Formoreinformationaboutthisport,seeSettingUptheGatewayExternalPorton page 224.
237
Frequently Asked Questions About Reverse HTTP Gateway

ThissectionprovidesanswerstosomefrequentlyaskedquestionsaboutReverseHTTP Gateway. 1 If I define the gateway external port on the Reverse HTTP Gateway Server to use HTTPS, do I need to define my gateway registration port to be an HTTPS port too? No.Thegatewayexternalportandthegatewayregistrationportoperate independently. 2 How many reverse connections should I register between the Reverse HTTP Gateway Server server and the Internal Server? Thatdependsontheexpectedloadandthesizeofthetransactions.Areverse connectionbetweentheReverseHTTPGatewayServerandInternalServeris availableexceptwhenarequestisbeingwrittentotheInternalServeroraresponseis beingreturnedfromtheInternalServer.Inotherwords,ReverseGatewayconnection utilizationisI/Obound.Therefore,ifyouexpectlarge,simultaneoustransactions, increasethenumberofregisteredconnectionsaccordingly. Ifyouhavenotdefinedaprivatethreadpoolfortheinternalregistrationport,then forbestresults,thesumofallconnectionsspecifiedintheMax Connectionsfieldforall theinternalregistrationportsshouldnotbeexceed10%ofthenumberofserver threadsspecifiedinServer Thread Pool Max Threads fieldontheSettings>Resourcespage. Ifyouhavedefinedaprivatethreadpoolfortheinternalregistrationport,thenthe numberofconnectionsyoucanspecifyislimitedtothemaximumnumberofthreads allowedintheprivatethreadpool. 3 Is there persistence with the Reverse HTTP Gateway Server? No.TheReverseHTTPGatewayServerisjustanetworkhopfortheincoming request. 4 I want to authenticate the SSL credentials of external clients. Where do I set up certificates? ThefollowingtableshowswheretosetupcertificatesforthedefaultReverseHTTP Gatewayconfiguration,inwhichtheInternalServerperformsclientauthentication.If youwanttoperformclientauthenticationontheReverseHTTPGatewayServeras well,seePerformingClientAuthenticationontheReverseHTTPGatewayServer onpage 237.
238
Reverse HTTP Gateway Server Gateway External Port Servercertificate Privatekey CAcertificate Directorythatcontainsalistof certificateauthoritiesthatthe ReverseHTTPGatewayServer trusts.Theserverusesthisdirectory whencheckingcertificates submittedbyexternalclients. Clientpubliccertificatemappedto theuserpresentedbytheexternal client.Addthiscertificatehereifyou areperformingclientauthenticationon theReverseHTTPGatewayServerin additiontotheInternalServer. Registration Port PubliccertificatetheInternalServer usestoregisterreverseconnections withtheReverseHTTPGateway Server.Thiscertificatemustbe mappedtoauserwithadministrator privileges.
Internal Server
Directorythatcontainsalistof certificateauthoritiestheInternal Servertrusts.Theserverusesthis directorywhencheckingcertificates submittedbyexternalclients. Clientpubliccertificatemappedto theuserpresentedbytheexternal client.
ClientcertificatethattheInternal ServerpresentstotheReverse HTTPGatewayServer.Ifthe registrationportoftheReverse HTTPGatewayServerrequires certificates,thiscertificatemustbe mappedtoanadministratoruseron theReverseHTTPGatewayServer.
InternalServersCAcertificate 5 Can I use the Reverse HTTP Gateway Server as my outbound proxy server as well? No.TheonlyrequeststhatgothroughtheReverseHTTPGatewayServerare inboundrequestsfromtheexternalclientdestinedfortheInternalServerand responsestothoserequestsfromtheInternalServerbacktotheexternalclient.Any nonsolicitedrequestsfromtheInternalServergodirectlytotheexternalclient. 6 Which components does Reverse Gateway support? TradingNetworksandwebMethodseStandardsmodules(includingEDI,ebXML, RosettaNetandCIDX).
239
What authentication mode should I use for the Reverse HTTP Gateway Server and the Internal Server? Authenticationmodeisthemethodaserverusestoauthenticateclientrequests.Ina defaultReverseHTTPGatewayconfiguration,theReverseHTTPGatewayServer receivesauthenticationinformationfromtheexternalclientandpassesitontothe InternalServer,whichperformstheauthentication. BesuretospecifythesameauthenticationmodefortheInternalServerandforthe gatewayexternalportontheReverseGatewayServer.Forexample,iftheInternal ServersauthenticationmodeisRequired,thegatewayexternalportontheReverse GatewayServermustalsobeRequiredsothattheReverseGatewayServeralways passestheexternalclientscertificatetotheInternalServer. Incontrast,theauthenticationmodeofthegatewayregistrationportontheReverse GatewayServerdoesnotneedtomatchtheauthenticationmodeoftheInternal Serverorthegatewayexternalport. IfyouwanttoperformclientauthenticationontheReverseHTTPGatewayServer, seePerformingClientAuthenticationontheReverseHTTPGatewayServeron page 237.
8 9
DoesReverseHTTPGatewaysupporttheFTPprotocol? No,itislimitedtoHTTPandHTTPSonly. AretheSOCKandSSLSOCKprotocolssupported? No,thesewereproprietaryprotocolsusedinthe4.xand6.xreleases.Startinginthe 7.1release,SOCKandSSLSOCKhavebeenreplacedbyHTTPandHTTPS.
10 IsitpossibletorunfilteringservicesontheReverseGatewayserver? No,filteringserviceswereavailableinthe4.xand6.xreleases,butarenotavailablein 7.x.
240
16
Outbound Passwords
242 242 244 244 245 246 246 248 248 251
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing Outbound Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing the Master Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing the Expiration Interval for the Master Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About the configPassman.cnf File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Outbound Password Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Master Password Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What To Do if You Lose or Forget Your Master Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . When There Are Problems with the Master Password or Outbound Passwords at Startup . . . . Email Listeners and Package Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
241
16 Outbound Passwords
Overview
Aspartofitsnormaloperations,theIntegrationServermayconnecttoapplicationsand subsystemssuchasremoteIntegrationServers,proxyservers,anddatabases.The IntegrationServer,actingasaclient,isrequiredtosupplyapassword,referredtoasan outboundpassword,toeachofthesesystemsbeforeconnectingtothem.TheIntegration Serverusestheoutboundpasswordstoidentifyitselforauthenticatetotheothersystems. WhenyouconfiguretheIntegrationServertoconnecttoanapplicationorsubsystem,for exampleadatabase,youspecifythepasswordtheIntegrationServermustsendtothe databaseserverinordertoconnecttoit.Later,whenanIntegrationServerusermakesa requestthatrequiresthedatabase,theIntegrationServersendstheconfiguredpassword tothedatabaseserverandconnectstoit. Toprotecttheseoutboundpasswords,theIntegrationServerencryptsthem.Bydefaultit encryptsthemusingPasswordBasedEncryption(PBE)technology,alsoknownas PKCS#5.Thisencryptionmethodrequirestheuseofanencryptionkeyormasterpassword thatyouspecify.Theencryptedoutboundpasswordsarestoredinafile. Note: Flowservicesmayalsostoreandretrieveoutboundpasswordstoaccesssecure resources,usingthepub.security.outboundPasswordsservices.Formoreinformation, seewebMethodsIntegrationServerBuiltInServicesReference. Themasterpasswordisalsoencrypted,andbydefault,isstoredinafile.However,when thepasswordisstoredinafile,thereisachancethatsomeonecouldaccessthefileand decryptthepassword.Therefore,forgreatersecurity,youcanconfiguretheIntegration Servertopromptforthemasterpasswordatserverstartupinstead. Important! Toprotectthemasterpasswordfile(ifyouuseone)andtheoutbound passwordsfile,assignthemoperatingsystemAdministratoraccess. Asstatedabove,outboundpasswordsareusedbytheIntegrationServertoauthenticate tootherentities.Incontrast,inboundpasswordsareusedbyusersandotherserversto authenticatetotheIntegrationServer.Inboundpasswordsarestoredasaonewayhash. SeeChapter 5,ManagingUsersandGroupsforadiscussionofsettingupinbound passwords. Thefollowingsectionsdescribehowtomanageoutboundpasswords.
Managing Outbound Passwords

WhenyoufirstinstalltheIntegrationServer,itisconfiguredtousePBEtoencrypt outboundpasswords,andhasamasterpasswordofmanagewithanexpiration intervalof90days. YoucanchangethemasterpasswordanditsexpirationintervalbyusingtheSecurity > Outbound PasswordscreenoftheIntegrationServerAdministrator.Youcanalsousethe IntegrationServerAdministratortoresetthemasterpasswordandallthestored
242
outboundpasswordsintheunlikelyeventthemasterpasswordoroutboundpasswords becomelostorcorrupted. Tochangeothersettings,youmustedittheconfigPassman.cnffile.Thosesettingsare: Encryptionmethodforoutboundpasswords MethodtheIntegrationServerusestoobtainthemasterpassword.TheIntegration Servercanstorethemasterpasswordinafileorpromptforitatserverstartup. Thefollowingtableliststhetasksyoucanperformandwheretofindinstructions: To change... Themasterpassword. Theexpirationintervalofthemaster password. Theencryptionmethodusedfor outboundpasswords. Thelocationoftheoutboundpassword store. Themethodusedtoobtainthemaster password,thatis,whethertheIntegration Serverpromptsforthemasterpassword atIntegrationServerstartupinsteadof storingitinafile. Therepeatlimitforthemasterpassword, thatis,howsoonapreviouslyused passwordcanbereused. Thelocationofthemasterpasswordstore. Alloutboundpasswordsandthemaster password. See... ChangingtheMasterPasswordon page 244 ChangingtheExpirationIntervalforthe MasterPasswordonpage 244 WorkingwithOutboundPassword Settingsonpage 246 WorkingwithOutboundPassword Settingsonpage 246 WorkingwithMasterPassword Settingsonpage 246
WorkingwithMasterPassword Settingsonpage 246 WorkingwithMasterPassword Settingsonpage 246 ResettingtheMasterPasswordand OutboundPasswordsonpage 250
Important! Asyoudowithotherimportantsystemfiles,youshouldregularlybackup thefilestheserverusestomaintainoutboundpasswords.Thesefilesare: config/txnPassStore.datStoresencryptedoutboundpasswords config/empw.datStoresencryptedmasterpassword config/configPassman.cnfSpecifiesoutboundpasswordconfigurationsettings config/passman.cnfNoneditableversionofconfigPassman.cnf Alwaysbackupandrestorethesefilestogether.Ifyouchangethenameorlocationof theoutboundpasswordstoreorthemasterpasswordstore,makesureyourbackup procedurebacksupthecorrectfiles.
243
Changing the Master Password

WhenyoufirstinstalltheIntegrationServer,themasterpasswordismanage.For securitypurposes,youshouldchangethemasterpasswordimmediatelyafterinstallation andagainonaregularbasis.Youshouldalsochangeitwhentherearepersonnel changes. Thedefaultexpirationintervalforamasterpasswordis90days.Astheexpirationdate nears,theIntegrationServerdisplaysthepasswordexpirationstatusontheIntegration Serverandsendswarningmessagestotheserverconsolestatingthatitistimetochange themasterpassword.IftheIntegrationServerisconfiguredforemailnotification,the IntegrationServerwillalsosendemailmessageswiththisinformationtotheconfigured addresses. Note: Tokeepoutboundpasswordssynchronizedwiththemasterpassword,the IntegrationServerdoesnotprocessrequeststostoreandretrieveoutbound passwordswhilethemasterpasswordisbeingchanged.Therefore,ifyoursystem hasmanyaliases,considerperformingthemasterpasswordchangeduringoffpeak hourstopreventanydecreaseinperformance. To change the master password 1 2 3 4 5 OpentheIntegrationServerAdministrator. IntheSecuritymenuoftheNavigationpanel,clickOutbound Passwords. ClickUpdate Master Password. Enterthecurrentpassword,thenenterandconfirmthenewpassword. ClickChange Password. Note: Ifyouhavelostyourmasterpassword,refertoDeterminingWhetherYou CanRestorethePasswordsonpage 249.
Changing the Expiration Interval for the Master Password

Thedefaultexpirationintervalforamasterpasswordis90days.Youcanseethecurrent expirationdatebylookingattheSecurity > Outbound Passwordsscreen. Note: Theexpirationintervalisarecommendedtimebetweenpasswordchanges.Ifyou donotchangethemasterpasswordbytheexpirationdate,theIntegrationServerwill continuetooperateusingtheexistingpasswordindefinitely.
244
To change the expiration interval for the master password 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickOutbound Passwords. ClickUpdate Expiration Interval. EnterthenewexpirationintervalindaysandclickUpdate.Themaximumintervalis 366days. Note: Althoughitisnotrecommended,youcanspecifyanintervalof0.Withthis setting,thepasswordwillnotexpireandnowarningswillbesenttotheIntegration ServerAdministratorortheserverlog.
About the configPassman.cnf File

TheconfigPassman.cnffilecontainsadditionalconfigurationsettingsforoutbound passwordencryptionthatarenotcontainedintheIntegrationServerAdministrator.The fileconsistsofanumberofproperties,someofwhicharecommentedoutinthedefault configuration. Important! TheconfigPassman.cnffilehasacompanionfile,passman.cnf.Ifyoumake changestoconfigPassman.cnffile,theIntegrationServerwillautomaticallyupdate passman.cnftoreflectthesechangeswhenyouinitializetheIntegrationServer.Never updatepassman.cnfdirectly. Asshipped,theconfigPassman.cnffilespecifiesthatoutboundpasswordswillbestored infileconfig/txnPassStore.datandencryptedusingPasswordBasedEncryption(PBE).In addition,itspecifiesthatthemasterpasswordwillbestoredinfileconfig/empw.dat. Propertiesthatcanbeusedtospecifyothersettingsarecommentedout. Ifyouwanttochangetheseoptionalsettings,youmustedittheconfigPassman.cnffile. Thefilemustalwaysspecifythefollowing: Encryptionmethodforoutboundpasswords Locationofthefilethatcontainstheoutboundpasswords MethodtheIntegrationServerusestoobtainthemasterpassword ThefollowingsectionsdescribetheconfigPassman.cnffileindetailandhowtochange outboundpasswordandmasterpasswordsettings.
245
Working with Outbound Password Settings

ThissectiondescribeshowtousetheconfigPassman.cnffiletochangesettingsfor outboundpasswords.SeeWorkingwithMasterPasswordSettingsonpage 246for instructionsonusingtheconfigPassman.cnffiletochangemasterpasswordsettings. Important! Determineyourstrategyforoutboundpasswordandmasterpassword behaviorbeforeyoulaunchandconfigureyourIntegrationServerthefirsttime.Ifyou changethesesettingsaftertheIntegrationServerhasbeenconfigured,themaster passwordandoutboundpasswordscanbecomeoutofsync. IfyouarenotalreadyfamiliarwiththeconfigPassman.cnffile,readAboutthe configPassman.cnfFileabovebeforeproceeding.
Controlling Name and Location of Outbound Password File

Thedefaultfilenameandlocationfortheoutboundpasswordfileis config/txnPassStore.dat.Tochangeit,locateandmodifythefollowingproperty:
outbound.password.field.fileName=config/txnPassStore.dat
Thispropertymustalwaysbepresentanduncommented.Ifyouwanttochangethefile nameorlocation,changethehighlightedareaonly.Youcanspecifyanabsoluteor relativepath.Inthepathname,usetheforwardslash(/)only;thebackwardslash(\)is notsupported.
Controlling Encryption of Outbound Password File

ThedefaultencryptionmethodfortheoutboundpasswordfileisPasswordBased Encryption(PBE).Tochangeit,locatethefollowingpropertiesanduncommenta differentmethod.Oneandonlyone ofthesepropertiesmustalwaysbeuncommented:
default.encryptor=EntrustPbePlus #default.encryptor=Base64 #default.encryptor=None PBE encryption--most secure Base64 encoding--not secure Clear text--not secure
Working with Master Password Settings

ThissectiondescribeshowtousetheconfigPassman.cnffiletochangesettingsforthe masterpassword.SeeWorkingwithOutboundPasswordSettingsonpage 246for instructionsonusingtheconfigPassman.cnffiletochangeoutboundpasswordsettings. IfyouarenotalreadyfamiliarwiththeconfigPassman.cnffile,readAboutthe configPassman.cnfFileonpage 245beforeproceeding.
246
Important! Determineyourstrategyforoutboundpasswordandmasterpassword behaviorbeforeyoulaunchandconfigureyourIntegrationServerthefirsttime.Ifyou changethesesettingsaftertheIntegrationServerhasbeenconfigured,themaster passwordandoutboundpasswordscanbecomeoutofsync. Bydefault,themasterpasswordisstoredinthefileconfig/empw.dat,butifyouprefer, youcanconfigureIntegrationServertopromptforthemasterpasswordatserver initialization.ThefollowingsectionsdescribehowtotellIntegrationServerwhich methodtouse.
Storing the Master Password in a File

Tostorethemasterpasswordinafile,usethefollowingproperties:
Controls whether the Integration Server stores the master password in a file (true) or prompts for it at server initialization (false). If this value is set to true, make sure the master.password.useGUI and master.password.field.attemptsLimit properties (described below) are commented out. Location of master password store. Use the forward slash (/) only; the backward slash (\) is not supported. Number of password changes required before you can reuse a password.
master.password.storeInFile=true
master.password.field.fileName=config/empw.dat master.password.field.repeatLimit=3
Prompting for the Master Password at Server Initialization

Topromptforthemasterpasswordatserverinitialization,usethefollowingproperties:
Use these properties only if you want the Integration Server to prompt for the password at server initialization, that is, you specified false for master.password.storeInFile.If you do not want Integration Server to prompt for the password at server initialization, make sure the following two properties are commented out. #master.password.field.useGUI=true Specify true to prompt for the password in a popup window. If you choose this method, you can start the server from the Windows start menu. This is the default if master.password.storeInFile (above) is set to false. Specify false to prompt for the password on the server console. If you choose this method, you cannot start the server from the Windows start menu. Number of unsuccessful login attempts permitted before Integration Server rejects the request.
#master.password.field.attemptsLimit=3
247
YoucannotconfiguretheIntegrationServertopromptforthemasterpasswordatserver initializationif: TheIntegrationServerrunsasaWindowsservice.RefertoChangingWhetherthe IntegrationServerisaWindowsApplicationorWindowsServiceonpage 33for moreinformation. TheIntegrationServerrunsasabackgroundapplicationonUNIX.
What To Do if You Lose or Forget Your Master Password

IfyourIntegrationServerisconfiguredtoencryptoutboundpasswordsusingPassword BasedEncryption(PBE),yourIntegrationServerwillhaveamasterpassword,whichis thekeyusedtoencryptoutboundpasswords.Youneedtoenterthemasterpassword wheneveryouwanttochangetoanewencryptionkey.Inaddition,someinstallationsare configuredsothattheIntegrationServerpromptsforthemasterpasswordwhenthe IntegrationServerinitializes;withoutthepassword,theIntegrationServerwillstartup insafemode,whichisdescribedbelow. Therefore,ifyouloseorforgetyourmasterpassword,youwillneedtorestoreitorreset it,dependingonthecircumstances.Formoreinformation,seeDeterminingWhether YouCanRestorethePasswordsonpage 249.
When There Are Problems with the Master Password or Outbound Passwords at Startup
IftheIntegrationServerdetectsaproblemwiththemasterpasswordoroutbound passwordsatstartup,itwillplaceyouinsafemode,whichisaspecialmodefromwhich youcandiagnoseandcorrectproblems. WhentheIntegrationServerisinsafemode,itdisplaystheIntegrationServer Administrator,buttheIntegrationServerisnotconnectedtoanyexternalresources. Whenyouareplacedintosafemodebecauseofproblemswiththemasterpasswordor outboundpasswords,youwillseethefollowingmessageintheupperleftcornerofthe ServerStatisticsscreenoftheIntegrationServerAdministrator:
Important! Whenyouareinsafemode,donotconfigureormodifyoutbound passwordsunlesstheyhavebeenresetaspartoftheReset All Outbound Passwordstask. Whenthereisaproblemwiththesepasswords,youcancorrecttheproblembyrestoring thepasswordsorresettingthem.Themethodyouchoosedependsontheproblemwith thepasswords.ThereareanumberofreasonstheIntegrationServerwillautomatically gointosafemode.
248
Passwords are Corrupted or Out of Sync Itispossiblethatthemasterpasswordfile,outboundpasswordfile,orbothare corrupted.Itisalsopossiblethatthesefilesareoutofsyncwitheachother.Thefilesare outofsynchwhenthekeyusedtoencryptthecontentsoftheoutboundpasswordfileis notthekeyinthemasterpasswordfile.Ineithercase,refertoDeterminingWhether YouCanRestorethePasswordsonpage 249forinstructions. You Entered the Wrong Master Password by Mistake Youmightbeinsafemodebecauseyouunintentionallyenteredthewrongmaster passwordwhenpromptedforitatserverstartup.Ifyouthinkthisisthecase,shutdown theIntegrationServerandrestartit,thistimespecifyingthecorrectmasterpassword whenprompted. Platform Locale Has Changed AnychangetotheOSlocaleordefaultencodingcanrendertheoutboundpasswordand masterpasswordfilesunreadablebytheIntegrationServer.Forthisreason,Software AG recommendsthatyoudonotchangeplatformlocaleaftertheIntegrationServerhasbeen installedandstarted.
Determining Whether You Can Restore the Passwords

Youcanrestorepasswordsifeitherofthefollowingistrue: Yourmasterpasswordandoutboundpasswordsarestoredinfilesandyouhave recentbackupsofbothandthepassman.cnffile. TheIntegrationServerisconfiguredtopromptforthemasterpassword,youhavea recentbackupoftheoutboundpasswordfileandthepassman.cnffile,andyouknow themasterpasswordforthatbackup. Youmustresetthepasswordsifanyofthefollowingistrue: Yourmasterpasswordandoutboundpasswordsarestoredinfilesandyoudonot haverecentbackupsthemasterpasswordfile,theoutboundpasswordfile,andthe passman.cnffile. TheIntegrationServerisconfiguredtopromptforthemasterpasswordandyoudo nothaverecentbackupsoftheoutboundpasswordfileandthepassman.cnffile. TheIntegrationServerisconfiguredtopromptforthemasterpasswordandyouhave lostorforgottenthemasterpassword.
249
Restoring the Master Password and Outbound Password Files

Beforerestoringthesefiles,makesureyouhavereadDeterminingWhetherYouCan RestorethePasswordsonpage 249todetermineifyoucanrestore,orifyouneedto reset. To restore the master password and outbound password files 1 Determinewhichfilesyouneedtorestore. Ifyourmasterpasswordisnotstoredinafile,thatis,yourIntegrationServerprompts youforamasterpasswordatserverstartup,thenyoucanrestorejusttheoutbound passwordfileandthepassman.cnffile.Otherwise,youmustrestorethemaster passwordfile,theoutboundpasswordfile,andthepassman.cnffilefrombackups. 2 Determinethenameandlocationofthefiles. Thepassman.cnffileisalwaysconfig/passman.cnf.Bydefault,themasterpassword fileisconfig/empw.datandtheoutboundpasswordfileisinconfig/txnPassStore.dat. Ifyouarenotsureofthelocationofthesefilesonyoursystem,lookatthefile config/configPassman.cnf.Forinformationaboutusingthisfile,seeAboutthe configPassman.cnfFileonpage 245. 3 4 5 ShutdowntheIntegrationServer. Copythereplacementfilestoappropriatedirectory. RestarttheIntegrationServer. Note: Alwaysbackupandrestorethemasterpasswordfile(ifyouuseone),the outboundpasswordfile,andthepassman.cnffiletogether.
Resetting the Master Password and Outbound Passwords

Beforeresettingthesepasswords,makesureyouhavereadDeterminingWhetherYou CanRestorethePasswordsonpage 249todetermineifyoureallyneedtoresetthe passwordsorifyoucanrestoretheminstead. Theresetprocedureclears(blanksout)thestoredoutboundpasswordsandresetsthe masterpasswordtomanage.Inaddition,youmustmanuallyreentertheappropriate passwordsforallapplicationandsubsystempasswordsontheirrespectiveconfiguration screensintheIntegrationServerAdministrator.
250
To reset stored outbound passwords and the master password 1 StarttheIntegrationServerifitisnotalreadyrunning.IfyourIntegrationServeris configuredtopromptyouforamasterpasswordduringserverinitialization,enter anyvalue. IntegrationServertakesyouintosafemode,whichistheIntegrationServer Administrator,butinamodethatisnotconnectedtoanyexternalresources. 2 3 4 IntheSecuritymenuoftheNavigationpanel,clickOutbound Passwords. ClickUpdate Master Password. ClickReset All Outbound Passwords. TheIntegrationServerdisplaysawarningscreen,tobesureyouwanttoresetthe passwords. 5 6 ClickReset Passwords. TheIntegrationServerasksagainifyouaresureyouwanttoresetthepasswords. ClickOK. Thisstepclearsthestoredoutboundpasswordsandchangesthemasterpasswordto manage. 7 8 FromtheOutbound Passwordsscreen,clickChange Passwordandchangethemaster passwordtosomethingotherthanmanage. RestarttheIntegrationServer. YouwillseeerrormessagesastheIntegrationServerattemptstoconnecttothe applicationsandsubsystemsforwhichtheservernolongerhaspasswordsstored. 9 Gototheconfigurationscreenforeachapplicationorsubsystemandreenterthe passwordrequiredfortheIntegrationServertoconnecttothatapplicationor subsystem.Screenstocheckincludethosethatdefineremoteserveraliases,cluster configuration,JDBCconnectionpools,emaillisteners,LDAPservers,proxyservers, Brokerconfiguration,andWmDB.
Email Listeners and Package Replication

Whenyouexportapackagethatisassociatedwithalistener,informationaboutthat listenerissentwiththepackage.However,inthecaseofanemaillistener,notallthe listenerconfigurationinformationissenttothedestinationIntegrationServer. Specifically,theoutboundpasswordthattheemaillistenerusestoconnecttotheemail Serverisnotsent.Asaresult,whenthelisteneronthedestinationIntegrationServertries toconnecttotheemailserver,theconnectionfails.Althoughthelistenerappearsonthe listofports,itwillnotbeenabled.Youwillalsoseeerrormessagesontheserverconsole.
251
Toenabletheport,gototheSecurity > Ports > Edit Email Client ConfigurationScreeninthe IntegrationServerAdministratorandupdatethePasswordfieldtospecifythepassword neededtoconnecttotheemailserver. Ifyouexportapackagethatisassociatedwithanemaillistenerfroma6.5Integration Servertoapre6.5IntegrationServer,theemaillistenerwillnotbereplicatedatall.You mustmanuallyreconfigurethelisteneronthepre6.5IntegrationServerafterinstalling thepackagethere.
252
17
Configuring a Central User Directory or LDAP

254 255 256 260 261 267 269 270 271
Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of How Integration Server Works with Externally Defined Users and Groups . . . . . . . Configuring Central User Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of Using LDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring the Server to Use LDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Considerations for User Accounts and Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Granting Administrator Privileges to External Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Granting Developer Privileges to External Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Granting Access to Services and Files to External Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
253
17 Configuring a Central User Directory or LDAP
Before You Begin

ThischapterdescribeshowIntegrationServerusesanexternaldirectorytoauthenticate clients,ratherthanusinginternallydefineduserandgroupinformation.Forinformation aboutusinginternallydefinedusersandgroups,refertoChapter 5,ManagingUsers andGroups.YoucansetupthewebMethodsIntegrationServertoaccessinformation fromanexternaldirectoryifyoursiteusesoneofthefollowingexternaldirectoriesfor userandgroupinformation: Centralusermanagement LightweightDirectoryAccessProtocol(LDAP) YoucanconfigureIntegrationServerforcentralusermanagementbyconnecting IntegrationServertoaMywebMethodsServeruserdatabase.Youcanalsoconfigure LDAPdirectoriesandothertypeofdirectoriestobeusedwithcentralusermanagement. However,youcanonlyuseoneexternaldirectoryatatime,acentraluserdirectoryor LDAP. Important! IfyouareusingMywebMethodsServerinyourenvironment,Software AG recommendsthatyouconfigureIntegrationServertoworkwithacentraluser managementdirectory.IfyouwanttouseanLDAPserverandyouareusingMy webMethodsServer,itisrecommendedthatyouconfigureLDAPusingMy webMethodsServer.ConfigureIntegrationServertoworkwithLDAPserverdirectly onlywhenyouarenotusingMywebMethodsServer. Beforeyoucontinuereadingthischapter,youmayfindithelpfultofirstunderstandhow IntegrationServerusesuserandgroupinformation.Readthefollowingsectionsifyou havenotalreadydoneso. Chapter 5,ManagingUsersandGroups SettingUpAdministratorsonpage 141 SettingUpDevelopersonpage 142 ControllingAccesstoResourceswithACLsonpage 168 BasicAuthentication(UserNamesandPasswords)onpage 188
254
Overview of How Integration Server Works with Externally Defined Users and Groups
ThefollowingsectionsprovideinformationabouthowandwhenIntegrationServer interactswithusersandgroupsdefinedinacentraluserdirectoryorinLDAP, specifically: HowexternallydefinedusersandgroupscanbeusedinIntegrationServer. WhenIntegrationServeraccessesinformationaboutexternallydefinedusersand groups. HowIntegrationServerauthenticatesuserswhobelongtoexternallydefinedgroups orroles.
How the Server Uses Externally Defined Users and Groups

Theservercanuseexternallydefinedinformationforthesamepurposesituses internallydefineduserandgroupinformation: Toauthenticateclientsusingusernamesandpasswords TocontrolwhocanconfigureandmanageIntegrationServer Tocontrolwhocancreate,modify,anddeleteservicesusingwebMethodsDeveloper TocontrolaccesstoservicesandfilesthatareavailableinIntegrationServer ExternallydefinedinformationdoesnotreplaceACLs.Tocontrolaccesstoservicesand files,youstillneedtosetuptheACLsthatidentifythegroupsthatareallowedand deniedaccesstospecificservicesandfiles.However,youcanassignexternallydefined groupstoanACL. WhenyouconfiguretheservertousecentralusermanagementorLDAPdirectory, externallydefinedusersandgroupsarenotdisplayedontheSecurity > User Management page.However,ifanexternalgrouphasbeenmappedtoanIntegrationServerACL,the groupwillbedisplayedontheSecurity > Access Control Lists page.
When the Server Accesses Externally Defined Information

Theserverobtainsexternallydefinedinformationinthefollowingcircumstances: Toauthenticateclients TodetermineifanACLallowsordeniesanaction Note: Clientrequeststhatrequiretheservertoaccessacentraluserdirectoryoran LDAPdirectorymaytakelongertocompletethanthosethatdonot.
255
How Integration Server Authenticates Externally Defined Clients

Whentheserverisauthenticatingaclientusingusernamesandpasswords,itfirst attemptstofindtheusernameandpasswordinternally.Ifitfindsaninternallydefined useraccountforthesuppliedusername,theserverauthenticatestheclientusingthe internallydefinedinformation.Ifthesuppliedpasswordiscorrect,theserverproceeds withtherequest.Ifthesuppliedpasswordisnotcorrect,theserverrejectstherequest. Iftheservercannotfindaninternallydefineduseraccountforthesuppliedusername, theserveraccessestheexternaldirectory(eitheracentraluserdirectoryorLDAP)to obtainusernameandpasswordinformationfortheclient.Ifitfindsanexternallydefined useraccount,theserverauthenticatestheclientusingtheexternallydefinedinformation. Ifthesuppliedpasswordiscorrect,theserverproceedswiththerequest.Ifthesupplied passwordisnotcorrect,theserverrejectstherequest. Note: Ifthepasswordsarecontainedinanexternalauthenticationsystemotherthan CentralUsersorLDAP,forexampleKerberos,youmustcreateyourownpluggable moduletoobtainthisinformation.SeeCustomizingAuthenticationonpage 189for informationaboutsettingupapluggablemodule. Iftheservercannotfindeitheraninternallyorexternallydefineduseraccountforthe user,theserverrejectstherequest. Iftheuserdoesnotsupplyausernameorpassword,theserverusestheinternally definedDefaultuseraccount.
Configuring Central User Management

Centralusermanagementinvolvesusingasinglelocationtostoreandmanage informationaboutusersofwebMethodsproducts.YoucanuseIntegrationServer AdministratortograntusersinacentraldirectoryaccesstoIntegrationServer functionalityandservices.Forexample,youcanassignaMywebMethodsServerroleor grouptoanACL. IfauserwillaccessIntegrationServerorTradingNetworksthroughMywebMethods interfaces,createtheusersinMywebMethodsServerandthenuseIntegrationServer Administratortogivethemaccesstothenecessaryareas.Ifsuchusersarealready definedinanexternaldirectorysuchasLDAP,youcanconfigureMywebMethods Servertoworkwiththeexternaldirectory. Usersdefinedinacentrallocation,suchastheMywebMethodsServeruserdirectory,are sometimesreferredtoascentralusers. Important! BeforeyoucanconfigurecentralusermanagementinIntegrationServer, MywebMethodsServermustalreadybeinstalledandconfiguredtouseanexternal database.Additionally,MywebMethodsServershouldhavebeenrestartedatleast oncetoenableMywebMethodsServerclustering.MywebMethodsServerdoesnot needtoberunningforIntegrationServertoaccesscentraluserinformation.
256
Toconfigurecentralusermanagement,youcompletethefollowingtasksinIntegration Server.
1
CreateaJDBCpoolaliasforconnectingtothecentraluserdatabase,i.e.,theMy webMethodsServerdatabase.WhenyoucreatetheJDBCpoolalias,you specifytheconnectiondatabaseneededtoconnecttotheMywebMethods Serverdatabase. AssociatetheCentralUsersfunctionalaliaswiththenewJDBCpoolaliasand initializetheconnectionpool.
Thefollowingsectionsprovidedetailedinformationaboutaccomplishingeachofthese tasks. To create a JDBC pool alias for connecting to a My webMethods Server database 1 2 3 OpenIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickJDBCPools. ClickCreate a new Pool Alias Definitionandcompletethefieldsasfollows: In this field... Alias Name Specify.... Namefortheconnectionpoolalias.Thenamecaninclude anycharactersthatarevalidforafilenameinyouroperating system. Descriptionfortheconnectionpoolalias. Databasedrivertouse. URLforthedatabaseserver.Belowaresampleformats. URL Oracle
jdbc:wm:oracle://server:{1521|port};serviceName=service [;option=value ]
Alias Description Associated Driver Alias Database URL
SQL Server
jdbc:wm:sqlserver://server:{1433|port}; databaseName=database[;option=value ]
DB2 for Linux, UNIX, Windows

jdbc:wm:db2://server:{50000|port};databaseName=database [;option=value ].
DB2 for iSeries

jdbc:wm:db2://server:{446|port};locationName=location [;option=value ]
257
In this field...
Specify.... Important! ForDB2,ifIntegrationServerwillconnecttoa schemaotherthanthedefaultschemaforthespecified databaseuser,youmustspecifytheseconnectionoptionsin theURL:

;AlternateId=schema;InitializationString="SET CURRENT PATH=schema"
AlternateIDisthenameofthedefaultschemathatisusedto qualifyunqualifieddatabaseobjectsindynamically preparedSQLstatements User Id Password Minimum Connections DatabaseuserforIntegrationServertousetocommunicate withthedatabase. Passwordforthedatabaseuser. Specify0. TheMywebMethodsServerdatabasemanagesthe minimumnumberofconnections.However,Integration ServerAdministratorrequiresthatavaluebeenteredhere. Specify1. TheMywebMethodsServerdatabasemanagesthe maximumnumberofconnections.However,Integration ServerAdministratorrequiresthatavaluebeenteredhere. Specify0. TheMywebMethodsServerdatabasemanagestheidle timeout.However,IntegrationServerAdministrator requiresthatavaluebeenteredhere. Note: TheMywebMethodsServerdatabasemanagesminimumconnections, maximumconnections,andtheidletimeout.Consequently,theproperties Minimum Connections,Maximum ConnectionsandIdle TimeoutareignoredbytheMy webMethodsServerdatabase. 4 5 ClickSave Settings. AssociatethenewJDBCpoolaliaswiththeCentralUsersfunctionalaliasusingthe procedureToassociatetheCentralUsersfunctionalaliaswiththenewJDBCpool alias,whichfollows.
Maximum connections
Idle timeout
258
To associate the CentralUsers functional alias with the new JDBC pool alias 1 2 3 OpenIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickJDBCPools. UnderFunctional Alias Definitions,intherowfortheCentralUsersfunctionalalias,click EditintheEdit Associationcolumn.YoumayneedtoscrolltotherighttoseetheEdit Associationcolumn. IntheSettings > JDBC Pools > Functional Definitionsscreen,intheAssociated Pool Aliaslist, selectthepoolaliasthatyoujustcreated.ClickSave Settings. UnderFunctional Alias Definitions,intherowfortheCentralUsersfunctionalalias,click RestartintheRestart Functioncolumn.Youmayneedtoscrolltotherighttoseethe Restart Functioncolumn.RestartingcreatesafreshJDBCpool. UnderFunctional Alias Definitions,intherowfortheCentralUsersfunctionalalias,click intheTest column.YoumayneedtoscrolltotherighttoseetheTestcolumn.This verifiesthatIntegrationServercanconnecttotheMywebMethodsServerdatabase. 7 RestartIntegrationServer. Notes: IntegrationServerupdatestheAnonymousACLautomaticallytoincludetheMy webMethodsUsersRolefromMywebMethodsServer. ForinformationaboutgivingcentralgroupsandrolesaccesstoACLs,seeAllowing orDenyingGroupAccesstoACLsonpage 174. Forinformationaboutgivingexternallydefinedusers,includingthosedefinedina centraluserdirectory,administratorprivilegesonIntegrationServer,seeGranting AdministratorPrivilegestoExternalUsersonpage 269 Forinformationaboutgivingexternallydefinedusers,includingthosedefinedina centraluserdirectory,developerprivilegesonIntegrationServer,seeGranting DeveloperPrivilegestoExternalUsersonpage 270 Forinformationaboutgivingexternallydefinedusersaccesstoaserviceorfile, seeGrantingAccesstoServicesandFilestoExternalUsersonpage 271.
4 5
Stopping Use of Central User Management

Atsomepoint,youmightwanttostopusingcentralusermanagement. To stop using central user management 1 2 OpenIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickJDBCPools.
259
UnderFunctional Alias Definitions,intherowfortheCentralUsersfunctionalalias,click EditintheEdit Associationcolumn.YoumayneedtoscrolltotherighttoseetheEdit Associationcolumn. OntheSettings > JDBC Pools > Functional Definitionsscreen,intheAssociatedPoolAlias column,selectNone. ClickSave Settings.IntegrationServerAdministratorpromptsyoutoconfirmthatyou wanttoupdatethefunctionalalias.ClickOK. RestartIntegrationServerforthechangestotakeeffect.
4 5 6
Overview of Using LDAP

IfyoursiteusesLightweightDirectoryAccessProtocol(LDAP)foruserandgroup information,youcanconfiguretheIntegrationServertoobtainuserandgroup informationfromtheexternaldirectory.Youcan,however,configureIntegrationServer tousemorethanoneLDAPdirectoryatatime,allowingIntegrationServertoworkwith differentLDAPdirectoriesforusersindifferentlocationsordifferentorganizations.In addition,youcanmaintainmultipleLDAPdirectoriessothatonedirectoryservesasa backupforanother. Important! IfyouwanttouseanLDAPservertostoreuserinformationandyouare usingMywebMethodsServer,itisrecommendedthatyouconfigureLDAPusingMy webMethodsServer.ConfigureIntegrationServertoworkwithLDAPserverdirectly onlywhenyouarenotusingMywebMethodsServer. LDAPprotocolsaredesignedtofacilitatesharinginformationaboutresourcesona network.Typically,theyareusedtostoreprofileinformation(loginID,password,etc.). Youcanalsousethemtostoreadditionalinformation.IntegrationServerusesLDAPfor performingexternalauthentication. UsingyourexistingLDAPinformationallowsyoutotakeadvantageofacentral repositoryofuserandgroupinformation.Systemadministratorscanaddandremove usersfromthecentrallocation.Usersdonotneedtorememberaseparatepasswordfor webMethodsapplications;theycanusethesameusernamesandpasswordsthatthey useforotherapplications.RemembertouseyourLDAPtoolstoadministerusersor groupsstoredinanexternaldirectory.
About LDAP and Caching

ForLDAP,afteraccessinguserinformation,theIntegrationServercachesittoimprove performance.Iftheinformationremainsinthecacheforonehourwithoutbeing accessed,orifthecachespaceisneededforamorerecentrequest,theIntegrationServer deletestheinformationfromthecache. Iftheserverreceivessubsequentrequeststhatrequiretheinformationithasincache,the IntegrationServerusesthecachedinformationratherthanaccessingtheexternal directory.
260
Configuring the Server to Use LDAP

ToconfiguretheservertouseLDAP,youneedto: InstructIntegrationServertousetheLDAPprotocol DefineoneormoreconfiguredLDAPserversthattheIntegrationServeristousefor theseusers Software AGrecommendsthatyouusecentralusermanagementinsteadofconfiguring IntegrationServertouseonemoreLDAPdirectoriesforexternalusermanagement.For moreinformationaboutcentralusermanagement,seeConfiguringCentralUser Managementonpage 256andtheMywebMethodsServerAdministratorsGuide. To specify LDAP as the external provider 1 2 3 4 5 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickUser Management. Click LDAP Configuration. ClickEdit LDAP Configuration. NexttoProvider,selectLDAP. IntegrationServerissuesaprompttoverifythatyouwanttochangethesetting.Click OK.IfyourIntegrationServerisconfiguredtocentralusermanagement,youmust disableitbeforeyoucanconfigureLDAP.Forinformationaboutdisablingcentral usermanagement,seeStoppingUseofCentralUserManagementonpage 259. 6 Enterthefollowinginformation: For this field Cache Size (Number of Users) Specify ThemaximumnumberofLDAPusersIntegrationServer cankeepinmemoryintheusercache.Thedefaultis10. Oncethelimitisreached,IntegrationServerselectsusers forremovalfromthecachebasedonhowlongtheyhave beenidle.Asaresult,activitycanextendthetimeauser remainsinthecache. Asageneralrule,specifyacachesizeequivalentto510% ofthenumberofusersinyourLDAPsystem.However,if onlyafewsessionsareeverloggedonsimultaneously,set thecachesizetobethesameasthenumberofsimultaneous sessions.
261
For this field Credential Time-to-Live (Minutes)
Specify ThenumberofminutesanLDAPuserscredentials(userid andpassword)canremaininthecredentialcachebefore beingpurged.Thedefaultis60minutes. Whenauserfirstattemptstologin,IntegrationServer createsauserobjectandcheckstheuserscredentials againsttheLDAPdirectory.IntegrationServerstoresthe credentialssothatsubsequentrequeststoauthenticatewill bemadeagainstthecachedcredentials,nottheLDAP directory. Forsecurityreasons,youcancontrolthelengthoftime thesecachedcredentialsarevalid.Thecredentialsare securebecausetheyarestoredusingaonewayhashing function,andcannotberecoveredfromthecache.Ifauser attemptstologinwithcredentialsthatdonotmatchthe cachedversion,IntegrationServerflushesthecacheand checksthecredentialsagainsttheLDAPdirectory.Ifthe credentialsarevalid,theIntegrationServercachesthem; otherwise,thecacheremainsempty. Fornormalsecureenvironments,atimetolivevalue betweenonehourandonedayisadequate.Forhigher securityenvironments,atimetoliveofbetweenoneand fiveminutesmaybemoreappropriate. TheTimetoLiveisabsolute;therefore,activitywillnot causethecredentialstoremainincachelonger.
ClickSave Configuration. TofinishconfiguringIntegrationServertouseanLDAPdirectory,continuetothe procedureTodefineanLDAPdirectorytoIntegrationServer,whichfollows. To define an LDAP directory to Integration Server
1 2 3 4
OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickUser Management. Click LDAP Configuration. ClickAdd LDAP Directory.
262
OntheSettings > LDAP Directory > Addscreen,enterthefollowinginformation: For this parameter Directory URL Specify ThecompleteURLoftheLDAPserver.TheURLhasthe formatprotocol://hostname:portnumber/DistinguishedName where TheprotocolisLDAPforstandardconnectionsorLDAPS forsecureconnections. ThehostisthehostnameorIPaddressoftheLDAP server.Theportistheportonwhichtheserverisrunning. Theportisoptional.Ifomitted,theportdefaultsto389 forLDAP,or636forLDAPS. TheDistinguishedNameisoptional,andisintheformof anLDAPdistinguishedname(DN),forexample dc=webMethods,dc=com,oro=webMethods.com,depending onhowyourdirectoryissetup.Thisdirectoryistheroot towhichallotherDNswillberelative. Forexample,specifyingtheURL
ldaps://ldapserv1:700/ou=Finance,o=acme.comwouldcreate
asecureconnectiontotheLDAPserverrunningonthenon standardport700onthehostcalledldapserv1.The connectioncreatedwillassumearootDNof ou=Finance,o=acme.comforallqueries. Ifyouspecifyldaps,IntegrationServerattemptstomakea secureconnectiontothedirectoryserverusinganSSLsocket. IfthedirectoryserverisconfiguredtouseSSL,itwillhavea servercertificateinplacetoidentifyitselftoclients.This certificatemustbesignedbyanauthoritytoproveitsvalidity (i.e.theservercertificateissignedbyaCA).Bydefault,the IntegrationServerwillonlytrustcertificatessignedbya signingauthoritywhoseCAcertificateisintheIntegration ServerstrustedCAsdirectory.RefertoChapter 11, SecuringCommunicationswiththeServerforinstructions onconfiguringthetrustedCAsdirectoryandfindingtheCA certificate. Principal TheuserIDtheIntegrationServershouldsupplytoconnect totheLDAPserver,forexample,o=webm.com or
dc=webm,dc=com.
ThisusershouldnotbetheAdministratoraccount,butauser thathaspermissiontoquerygroupsandgroupmembership. IfyourLDAPserverallowsanonymousaccess,leavethis fieldblank.
263
For this parameter Credentials
Specify ThepasswordtheIntegrationServershouldsupplyto connecttotheLDAPserver,thatis,thePrincipalspassword. TheIntegrationServerencryptsthispasswordaccordingto thesettingsspecifiedontheOutbound Passwords screen.For moreinformation,seeChapter 16,OutboundPasswords. ThenumberofsecondstheIntegrationServerwillwaitwhile tryingtoconnecttotheLDAPserver.Afterthistimehas passed,theIntegrationServerwilltrythenextconfigured LDAPserveronthelist.Thedefaultis5seconds.Increase thisnumberifyournetworkhaslatencyproblems.Ifmost requestswillbefrombatchprocesses,youcanincreasethis numbertobe30secondsormore. Theminimumnumberofconnectionsallowedinthepool thattheIntegrationServermaintainsforconnectingtothe LDAPserver.WhentheIntegrationServerstarts,the connectionpoolinitiallycontainsthisminimumnumberof connections.TheIntegrationServeraddsconnectionstothe poolasneededuntilitreachesthemaximumallowed,which isspecifiedintheMaximum Connection Poolfield.Thedefaultis 0. Themaximumnumberofconnectionsallowedinthepool thattheIntegrationServermaintainsforconnectingtothe LDAPserver.WhentheIntegrationServerstarts,the connectionpoolinitiallycontainsaminimumnumberof connections,whicharespecifiedintheMinimum Connection Poolfield.TheIntegrationServeraddsconnectionstothe poolasneededuntilitreachesthemaximumallowed.The defaultis10. Buildsadistinguishednamebyaddingaprefixandsuffixto theusername. TheSynthesizeDNmethodcanbefasterthantheQueryDN method(seebelow)becauseitdoesnotperformaquery againsttheLDAPdirectory.However,ifyourLDAPsystem doesnotcontainallusersinasingleflatstructure,usethe QueryDNmethodinstead. DN Prefix AstringthatspecifiesthebeginningofaDNyouwantto passtotheLDAPserver. DN Suffix AstringthatspecifiestheendofaDNyouwanttopasstothe LDAPserver.
Connection Timeout (seconds)
Minimum Connection Pool Size
Maximum Connection Pool Size
Synthesize DN
264
For this parameter
Specify Forexample,iftheprefixiscnandthesuffixis,ou=Users andauserlogsinspecifyingbob,theIntegrationServer buildstheDNcn=bob,ou=UsersandsendsittotheLDAP serverforauthentication. Note: Besuretospecifyallthecharactersrequiredtoforma properDN.Forinstance,ifyouomitthecommafromthe suffixabove,thatis,youspecifyou=Usersinsteadof ,ou=Users,theIntegrationServerwillbuildtheinvalidDN (cn=bobou=Users).
Query DN
Buildsaquerythatsearchesaspecifiedrootdirectoryforthe user. UsethismethodinsteadoftheSynthesizeDNmethod(see above)ifyourLDAPdirectoryhasacomplexstructure. UID Property ApropertythatidentifiesanLDAPuserid,suchascnor uid. User Root DN Thedistinguishednameofthelocationyouwanttostart searchingontheLDAPserver. Forexample,ifyouspecifycnfortheUIDpropertyand ou=usersfortheuserroot,theIntegrationServerwillissuea querythatstartssearchingintherootdirectoryou=usersfora commonnamethatmatchesthenametheuserloggedin with.
265
For this parameter Default Group
Specify AnIntegrationServergroupwithwhichtheuserisassociated. Theuserisallowedtoaccessservicesthatmembersofthis IntegrationServergroupcanaccess.Thisaccessiscontrolledby theACLswithwhichthegroupisassociated. IfyoualsospecifyavalueintheGroup Member Attributefield, theuserhasthesameaccessasmembersoftheIntegration ServergroupandmembersofLDAPgroupsthathavebeen mappedtoanIntegrationServerACL. Important! DonotspecifyAnonymousasthedefaultgroupif anyuserinthisgroupneedstohaveadministratorprivileges. ThedefaultACLdeniestheAnonymousgroupandwillnot allowaccesstherootpage.Choosetheappropriategroupin theDefault GroupfieldtoensurethattherequiredACLsget assignedtoyourgroup. Note: YoumustspecifyavalueintheGroup Member Attribute field,theDefault Groupfield,orboth.
Group Member Attribute
Thenameoftheattributeinagroupsdirectoryentrythat identifieseachmemberofthegroup.Thisvalueisusually memberoruniqueMember,butcanvarydependingon theschemaoftheLDAPdirectory. IntegrationServerusesthisinformationduringACL checkingtoseeiftheuserattemptingtologinbelongstoan LDAPgroupthathasbeenmappedtoanACL. Ifnovalueisspecifiedhere,IntegrationServerdoesnotcheck formembershipinanLDAPgroup.Asaresult,theusersability toaccessIntegrationServerservicesiscontrolledbythe IntegrationServergroupspecifiedintheDefault Groupfield. Note: YoumustspecifyavalueintheGroup Member Attribute field,theDefault Groupfield,orboth.
Group ID Property Group Root DN 6 ClickSave Changes.
ApropertythatidentifiesanLDAPgroup,suchasCN Thedistinguishednameofthelocation(rootnode)atwhich youwanttostartsearchingforusersontheLDAPserver.
TheLDAPDirectoryListdisplaystheaddedtheLDAPdirectory.
266
7
.
ClickMove Up/Move Downtoorderthedirectoriesinthelistbasedontheirpriority. Note: IfyoudefinemultipleLDAPservers,IntegrationServerwillsearchtheLDAP directoriesintheorderinwhichtheyaredisplayedontheSecurity > User Management > LDAP Configurationscreen.IfIntegrationServerdoesnotfindtheuserinthefirstLDAP directory,itwillsearchinorderthroughthelist.
Mapping an LDAP Users Access to ACL(s)

AswithIntegrationServergroups,youcanassociateLDAPgroupswithACLstocontrol accesstoIntegrationServerresources.AssociatinganLDAPgroupwithanACLis referredtoasmapping.ACLmappingtoLDAPgroupscanbedonedirectlythroughthe Security > ACLspage.FormoreinformationaboutallowinggroupsaccesstoACLs,see Chapter ,ControllingAccesstoResourceswithACLs.
Stopping Use of an LDAP as an External Directory

IfyounolongerwanttouseLDAPasanexternaldirectory,youcanupdatethe configurationtoremovetheexternaldirectoryconfigurationsettings. To stop using a LDAP as an external directory 1 2 3 4 5 6 7 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSecuritymenuoftheNavigationpanel,clickUser Management. ClickEdit LDAP Configuration. ClickLocalintheProviderfield. ClickSave Configuration. ClickOK. RestartyourIntegrationServer.
Considerations for User Accounts and Groups

Thissectionprovidesinformationaboutuseraccountsandgroupsthatyoushould considerifyouareusinganexternaldirectoryforuserandgroupinformation. You should keep internal and external user accounts and group names unique. Itmightget confusingifyouhaveanexternaluseraccountthathasthesameusernameasan internaluseraccountoranexternalgroupwiththesamegroupnameasaninternal group.Ifyoudohaveidenticallynamedusernamesorgroupnames,theserver alwaysusestheinternallydefinedinformation. Toavoidconfusion,itisrecommendedthatyoudonotsetupuseraccountsorgroups internallyifyouareusinganexternaldirectory.Theexceptionsarethepredefined
267
useraccountsDefault,Administrator,Developer,Replicator,andthepredefined groupsEverybody,Administrators,Developers,Replicators,andAnonymous.You cannotdeletetheseuseraccountsandgroups;therefore,makesuretheinternal accountsandgroupshavethecorrectdefinitions. Important! AlthoughIntegrationServerisdistributedwithapredefinedReplicator account,youcanuseadifferentaccountforpackagereplication.Aslongasthe subscriptionrequesterspecifiesanaccountthatisamemberofagroupthatis assignedtotheReplicatorsACL,thatusercanperformreplication. Whenpublishingapackagetoanotherserver,thepublishingserverusesthe accountspecifiedbythesubscriptionrequester.Forexample,ifthesubscription requester(eitherthepublisherorthesubscriber)specifiedaccountDEPT01,the publisherwilllogintothesubscriberserverasDEPT01.DEPT01mustbea memberofagroupthatisassignedtotheReplicatorsACLonthesubscriber server. RefertosectionCopyingPackagesfromOneServertoAnotherinChapter 18, ManagingPackagesformoreinformationaboutpackagereplication.
webMethods Integration Server Users
External Directories
Replicator
Administrator
Developer
Admin
Lindsay
Rebecca
Groups
Replicators
Administrators
Developers
Admins
ISDevs
Anexceptiontotheabovediagramisthatallinternallydefinedusersaremembersofthe internallydefinedEverybodygroup. You cannot use the Integration Server Administrator to manage (i.e., create, edit, or delete) Central Users. YoumustuseMywebMethodsServertoadministerCentralUsersand Directories.RefertotheMywebMethodsServerAdministratorsGuideformore information. You cannot use the Integration Server Administrator to manage (i.e., create, edit, or delete) LDAP user and group information.TomakechangestoLDAPdirectories,followyoursites standarddirectoryupdateprocedures.
268
Granting Administrator Privileges to External Users

TheAdministratorsACLcontrolswhohasadministratorprivileges.Becauseyoucannot assignexternallydefineduserstointernallydefinedgroups,youcannotgrantexternally definedusersadministratorprivilegesbyassigningthemtotheinternallydefined Administratorsgroup.Instead,youneedtosetupanexternallydefinedgroupfor administrators.Then,addtheexternallydefinedgroupofadministratorstothe AdministratorsACL. TomakeagroupofcentralusersISAdministrators,youwillneedtoaddtheirgroupor roletothefollowingACLs: AdministratorsACL DefaultACL DevelopersACL InternalACL ReplicatorsACL AnonymousACL(iftheirrole/groupisnotpartofthisalready) Note: IfyouconfiguredIntegrationServertousecentralusermanagement,the AnonymousACLautomaticallyincludestheMywebMethodsusersrole.
External Directory
Users
Administrator
Frances
Megan
Groups
Administrators
ISAdmins
ACLs
Administrators
To grant administrator privileges to an externally defined user 1 2 Setupanexternallydefineduseraccountfortheuserifonedoesnotalreadyexist. Setupanexternallydefinedadministratorsgroupifonedoesnotalreadyexist. Important! DonotnametheexternallydefinedgroupAdministrators.Thename ofthegroupmustnotbethesamenameasanyinternallydefinedgroup.
269
3 4
Maketheexternallydefineduseramemberoftheexternallydefinedadministrators group(ISAdminsinthepictureabove). UpdatetheAdministratorsACLtoincludetheexternallydefinedadministrators groupintheAllowedlist. RefertoAllowingorDenyingGroupAccesstoACLsonpage 174forinformation onhowtoincludeexternallydefinedadministratorstotheAllowedlist.
Granting Developer Privileges to External Users

TheDevelopersACLcontrolswhocanconnecttotheIntegrationServerfromthe Developertocreate,modify,anddeleteservicesthatresideontheserver.Becauseyou cannotassignexternallydefineduserstointernallydefinedgroups,youcannotgrant externallydefinedusersdeveloperprivilegesbyassigningthemtotheinternallydefined Developersgroup.Instead,youneedtosetupanexternallydefinedgroupforthe webMethodsDeveloper.Then,addtheexternallydefinedgrouptotheDevelopersACL.
webMethods Integration Server External Directory
Users
Developer
Lindsay
Rebecca
Groups
Developers
ISDevs
ACLs
Developers
To grant developer privileges to an externally defined user 1 2 Setupanexternallydefineduseraccountfortheuserifonedoesnotalreadyexist. Setupanexternallydefineddevelopersgroupifonedoesnotalreadyexist. Important! DonotnametheexternallydefinedgroupDevelopers.Thenameof thegroupmustnotbethesamenameasanyinternallydefinedgroup. 3 4 Maketheexternallydefineduseramemberoftheexternallydefineddevelopers group(ISDevsinthepictureabove). UpdatetheDevelopersACLtoincludetheexternallydefineddevelopersgroupinthe Allowedlist. RefertoAllowingorDenyingGroupAccesstoACLsonpage 174forinformation onhowtoincludeexternallydefineddeveloperstotheAllowedlist.
270
Granting Access to Services and Files to External Users

YoucreateACLsthatcontrolaccesstoservicesandfilesandassignthemtothespecific servicesandfilesthatyouwanttoprotect. Tograntaccesstoaserviceorfile,theserverfirstusesinternallydefinedinformationto determinewhethertheclientisamemberofallowedordeniedgroupslistedintheACL. Iftheservercannotfindtheinformationinternally,itobtainsexternallydefined informationtodetermineiftheACLallowsordeniesaccess. Ifyouwanttoallowanexternallydefineduseraccesstoaserviceorfile,updatetheACL thatprotectstheserviceorfiletoidentifytheexternalusersgrouporroleasanAllowed groupintheACL.Similarly,ifyouwanttoexplicitlydenyanexternallydefineduser accesstoaserviceorfile,updatetheACLthatprotectstheserviceorfiletoidentifythe externalusersgrouporroleasaDeniedgroupintheACL.
webMethods Integration Server Users External Directory Daniel Leanna
Groups
Finance
Marketing
ACLs
Finance
ACL Name
Finance
Everybody Administrators Developers Replicators Finance Marketing Everybody Administrators Developers Replicators Finance Marketing Daniel is granted access to the services protected by the Finance ACL because his external group is an Allowed group.
Allowed Groups
Denied Groups
Leanna is denied access to the services protected by the Finance ACL because her external group is a Denied group.
271
272
18
Managing Packages
274 277 280 288 288 292
Using Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How the Server Stores Package Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Finding Information about Your Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Copying Packages from One Server to Another . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
273
18 Managing Packages
Using Packages
Apackagecontainsasetofservicesandrelatedfiles,suchasspecifications,document types,andDSPs.Whenyouaddaservice,specification,documenttype,orDSPtothe webMethodsIntegrationServer,youmustaddittoapackage.Useapackagetogroup servicesandrelatedfiles. Byplacingrelatedfilesinapackage,youcaneasilymanagealltheservicesandfilesin thepackageasaunit.Forexample,youcanmakethemallavailable,disablethem,refresh them,ordeletethemwithoneaction.Additionally,ifyouhavemorethanone IntegrationServerinstalled,youcanusepackagemanagementfeaturestocopysomeor allservicesandfilesinapackagetoanotherserver. Youcangroupyourservicesusinganypackagestructureyouchoose,thoughmost organizationsgroupservicesintopackagesbyfunctionorapplication.Forexample,you mightputallpurchasingrelatedservicesinapackagecalledPurchaseOrderMgtand alltimereportingservicesintoTimeCards. Important! Everyserviceontheservermustbelongtoapackage.Beforeyoucanmake aserviceavailableforexecution,youmustloadthepackagetowhichitbelongs. AccesstoapackageanditscontentsiscontrolledthroughAccessControlLists(ACLs). UsingACLs,youcontrolwhocandisplayapackagefromtheIntegrationServer AdministratorandDeveloper,whocaneditthecontentsofapackage,andwhocan executeservicescontainedinthepackage.Formoreinformationaboutprotecting packages,seeControllingAccesstoResourceswithACLsonpage 168. Youcanassociateapackagewithaspecificportsothatwhenyoureplicatethepackage,it continuestouseaportwiththesamenumberonthenewserver.SeeSettingUpAliases forRemoteIntegrationServersonpage 68formoreinformationaboutassociatinga packagewithaport. Important! Becarefulwhenreplicatingapackagethatisassociatedwithaport;thenew portmightdecreasesecurityonthetargetsystem.Forexample,supposeyoureplicate apackagethatisassociatedwithanHTTPportat5556.Thereplicationprocess createsanHTTPportat5556onthetargetserver.Ifthetargetservernormallyuses onlyHTTPSportsbecauseoftheirgreatersecurity,thenthenewportpresentsa possiblesecurityholeonthatserver.
274
Predefined Packages
IntegrationServercomeswithavarietyofpredefinedpackages.Thetablebelowlistscore IntegrationServerpackages. Package Default Description IntegrationServerlooksinthispackageifauseraccessesthe serverwithoutspecifyingapackagename(forexample,by usingtheURLhttp://localhost:5555).Youcanalsouseittostore elementsyoucreatewithoutfirstcreatingapackage. Note: IntegrationServersearchesthepubdirectoryintheDefault packageforanindex.dsporindex.htmlfile.Asshipped,thepub directorycontainsanindex.htmlfilethatpointstheusertoan index.dspfileintheWmRootpackage.Thisindex.dspfileloads theIntegrationServerAdministrator.Topreventauserfrom inadvertentlyaccessingtheIntegrationServerAdministrator, youcanedittheindex.htmlfileinDefault/pubandchangeitto pointtoaninnocuouspage.SeeStage7:SettingUpSecurity onpage 403formoreinformation. WmRoot ThispackageprovidescoreIntegrationServerfunctionalityand auxiliaryfiles. Important! Donotalterordeletethispackage. WmTomcat ThispackagecontainstheTomcatJSP/servletenginedeveloped bytheApacheSoftwareFoundation(http://www.apache.org/). Usingthisengine,developerscandeployandexecute JavaServerPages,Javaservlets,andtheirsupportingfileswithin theIntegrationServerenvironmentorincorporateWeb applicationsintoneworexistingwebMethodspackages. ThispackagesupportswebMethods6orlateradapters. ThispackagewritesinformationaboutIntegrationServer packagestoaMetadataLibrary.Usingthissharedlibrary,users canaccessassetscreatedbyotherusers.Formoreinformation abouttheMetadataLibrary,seethewebMethodsMetadataLibrary UsersGuide.
WmART WmAssetPublisher
275
ThepackagesinthetablebelowprovideservicesthatenableyouorotherwebMethods productstoperformcertaintasks. This package... WmARTExtDC WmISExtDC WmTNExtDC Contains services that... InfrastructureDataCollectorusestodiscover andmonitoradaptersinstalledonIntegration Server,IntegrationServeritself,andTrading NetworksServer,respectively. IntegrationServerusestoextractandpublish metadataaboutitsservicestowebMethods MetadataLibrary. Supportbusinessprocessesmodeledin webMethodsDesigner. FlowservicesortheFilePollingprocessing servicecancalltoinitiallyacceptand consumeinboundflatfiles. Supportbusinessprocessesmonitoredusing webMethodsOptimize. Youcancallfromyourclientapplicationsand services. For more information... webMethods InfrastructureData Collector Administrators Guide webMethods MetadataLibrary UsersGuide Designeronline help webMethods IntegrationServer BuiltInServices Reference Optimize documentation webMethods IntegrationServer BuiltInServices Reference webMethodsProcess EngineUsersGuide webMethodsTask EngineUsersGuide
WmAsset Publisher WmDesigner WmFlatFile
WmOptimize WmPublic
WmPRT WmTaskClient WmUDDI
Supportbusinessprocessesexecutedusing thewebMethodsProcessEngine. Supporttasksdevelopedusingthe webMethodsTaskEngine. EnableyoutoqueryandpublishtoaUDDI v2directory. Note: Thispackageisdeprecatedin IntegrationServer7.1.Youshoulduse DevelopertointeractwithUDDIv3 directories.
WmVCS
EnableyoutostoreDeveloperelementsina sourcecontrolsystem.
webMethodsVersion ControlSystem Integration DevelopersGuide
276
This package... WmWin32
Contains services that... YoucanusetocallmethodsonCOMobjects, andWindowsspecificsamples,suchas sampleVisualBasicservices. Note: Thispackageisdeprecatedin IntegrationServer7.1
For more information... webMethods DeveloperUsers Guide
WmXSLT
YoucanusetotransformXMLdatafromone formatorstructuretoanother.
webMethods IntegrationServer BuiltInServices ReferenceandXSLT ServicesDevelopers Guide
Sample Package
TheWmSamplespackagecontainssampleservices.YoucanfindtheWmSamples packageinthecertifiedsamplesareaoftheKnowledgeBaseontheAdvantageWebSite.
How the Server Stores Package Information

Theserverphysicallystorespackageinformationinthe IntegrationServer_directory\packagesdirectory.Theservercreatesanewsubdirectoryfor eachpackage.Thenameofthesubdirectoryisthenameofthepackage.Forexample,ifa packageisnamedTimeCards,theservercreatesthe IntegrationServer_directory\packages\TimeCardsdirectorytoholdthefilesforthe package.
277
Whenyoucreateanewpackage,theservercreatesthefollowingsubdirectoriestohold allthefilesassociatedwiththepackage: PackageName

code classes jars static source ns pub doc resources templates web Namespace of the package Web documents .........Package documentation Resource Bundle Files Templates JSPs Java services
The code subdirectoryholdstheJavaandC/C++servicesthatbelongtothispackage. Withinthecodesubdirectoryaretheclasses,jars,static,source,andlibsubdirectories: TheclassessubdirectoryisforJavaclassesfortheJavaandC/C++services. ThejarssubdirectoryisforJavaclassesthatarepackagedtogetherinjarfiles. ThestaticsubdirectoryisalsoforJavaclassesthatarepackagedtogetherinjar files.Placethejarfilesinthislocationwhenyouwanttomakethemavailableto otherpackagesintheIntegrationServerandalsotopackagesinotherIntegration Serversystems. Whenyouplacejarfilesinthestaticsubdirectory,thenatstartuptheIntegration Serverautomaticallyloadsthesefilestotheserverclasspath.Also,thejarfilesare availabletootherpackagesevenwhentheimmediatepackageisdisabled. Note: TheIntegrationServerdoesnotautomaticallycreatethestatic subdirectorywhenyoucreateanewpackage.Thissubdirectoryisuser defined. ThesourcesubdirectoryisforthesourceofJavaservices. Thelibssubdirectory(notshownhere)holdsDLLsorspecializedlibrariesthat theJavaandC/C++servicesuse. Note: TheIntegrationServerdoesnotautomaticallycreatethelibsdirectory becausethedirectorysexistencepreventsyoufromreloadingapackage withoutrestartingtheserver.Youcannotreloadapackagethatusesshared libraries;youmustrestarttheserver.
278
Foreaseofadministration,placeservicesthatusesharedlibrariesinthesame package. The ns subdirectoryholdsflowservices,specifications,documenttypes,schemas, triggers,adapternotifications,adapterdocuments,adapterservices,adapter connectors,andcodefragmentsforJavaservices. The pub subdirectoryholdsWebdocumentsforthepackage.Forinstructionsonhowto accesstheWebdocumentsforapackage,seeDisplayingDocumentationfora Packageonpage 287. The doc subdirectoryholdsdocumentationforthepackage. The resources subdirectoryholdsresourcebundles<bundle.properties>,suchas applicationdata(notuserdata),whichiskeptseparatefromtheIntegrationServer application.Thefollowingitemsrepresenttypicalresourcesinsideabundle: Icons Windowpositions Dialogboxdefinitions Programtext Menus YoucaneasilymodifyandupdatevariousaspectsoftheIntegrationServerwithout reinstallingtheentireapplication.AJapaneselanguagepackfortheIntegration Serverisanexampleofaresourcebundlethatcontainslanguageandimagefilesfor theJapaneseversionoftheserver. The templates subdirectoryholdsoutputtemplatesthatareassociatedwiththispackage. The web subdirectoryholdsJSPsthatareassociatedwiththispackage.
Manifest File
Eachpackagehasamanifestfile.Itcontains: Indication of whether the package is enabled or disabled.Theserverdoesnotloaddisabled packagesatserverinitializationandyoucannotaccesselementsthatresidein disabledpackages. List of startup, shutdown, and replication services, if any, for the package.Formore informationaboutstartup,shutdown,andreplicationservicesandhowtoidentify them,seeRunningServicesWhenPackagesAreLoaded,Unloaded,orReplicated onpage 337. Package description.Abriefdescriptionofthepackage. Version information.Packageversionandbuildnumber.AlsoincludedistheJVM versionunderwhichthepackagewaspublished.
279
Patches applied.Alistofpatchesthathavebeenappliedtothepackage.Theseare namesornumbersthataremeaningfultoyourinstallation,possiblyobtainedfrom yourproblemtrackingsystem. Package dependencies, if any, for the package.Foraspecificpackage,thedevelopercan identifyotherpackagesthattheservershouldloadbeforeitloadstheelementsina particularpackage.Inotherwords,thedevelopercanidentifywhenonepackage dependsonanother.Forinformation,seeDisplayingInformationaboutaPackage onpage 284andthewebMethodsDeveloperUsersGuide. Target package name.Nameofthepackage. Publishing server.TheIntegrationServerthatpublishedthepackage.Ifthepackagehas notbeenpublished,thisfieldcontainsNone. Themanifestforapackageisinthemanifest.v3fileinthetopdirectoryforthepackage.
Finding Information about Your Packages

Theserverdisplaysavarietyofinformationaboutyourpackages.Thesectiondescribes theinformationthatisavailableandtheprocedurestousetodisplaytheinformation. Information Listofallofthepackagesthatresideonyourserver Listofspecifiedpackagesthatresideonyourserver Statusofwhethertheserversuccessfullyloadedthepackageornot Statusofwhetherthepackageisenabledordisabled Versionnumberofthepackage Numberofelementsinapackagethattheserversuccessfullyloadedinto memory NameofAccessControlList(ACL)thatcontrolswhichuserscanlistthe package Listofelementsinapackagethattheserverfailedtoloadintomemory Listofloaderrorsforthepackage Listofstartup,shutdown,andreplicationservicesinapackage Listofpackagesonwhichapackagedepends Listofserversthatsubscribetothispackage Documentationforthepackage Refer to page: 281 281 283 283 284 284 284 284 284 284 284 284 287
280
Viewing the Packages that Reside on Your Server

ThemainpackagemanagementscreenoftheIntegrationServerAdministratorlistsall packagesthatresideonyourserver.Italsodisplayswhethertheserversuccessfully loadedthepackageandwhetherthepackageisenabled. Note: TheserverdisplaysonlypackagestowhichyouhaveListaccess.
To view the packages that reside on the server 1 2 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuoftheNavigationpanel,clickManagement.
Filtering the List of Packages

Bydefault,themainpackagemanagementscreenlistsallthepackagesthatresideon yourserver.Youcanusethefiltertolimitthepackagestobedisplayed,makingthelist shorterandmoremanageable.YoucanmanagethePackages Listinthefollowingways: Filterthedefaultlistofpackagesbyspecifyingafullorpartialpackagename,and thenincludingorexcludingpackagesthatmatchthespecifiedcriteria. Narrowdownalistbyfilteringtheresultsagain. Tip! ClickShow All Packagestodisablefilteringandrestorethedefaultlistofall packagesontheserver. Filtering the Package List 1 2 InthePackagesmenuoftheNavigationpanel,clickManagement.ThePackages Listwill displayallthepackagesonyourserver. ClickFilter Packages.ThefilteringoptionswillappearabovethePackages List. Note: WhenFilter Packagesisenabled,anychangestotheIntegrationServer(such asnewpackages,etc.)willnotbereflectedinthePackages List.Whenyouclick Show All Packages andreturntonormalmode,thelistwillbeupdated.
281
Selectsomeorallofthefollowingoptions: Option Filter criteria Description Thestringyouwanttosubmittothefilter.Bydefault, packageswithnamesthatmatchthestringareincludedinthe results.Filtercriteriacanbeliteralsoracombinationofliteral andwildcardcharacters.The*(asterisk)and?(question mark)aretheonlysupportedwildcardcharacters.Leaving thefiltercriteriablankincludesallpackages. Important! ThepackagenamesintheFilter criteriafieldare casesensitive.Forexample,ifyouenterwma*,thefilterwill ignoreanypackagesbeginningwithWmA. Include Enabled Include Disabled Include Both Filter on result Exclude from result Specifywhethertoincludeonlypackagesthatareenabled (thosewithYesintheEnabledcolumnofthePackages List),only thosethataredisabled(NoisintheEnabledcolumn),orto includebothenabledanddisabledpackages. Enablethisoptionwhenyouhavealreadyfilteredthelistand youwanttorefiltertheresults,ratherthanthedefaultlist. Enablethisoptiontodisplaythepackagesthatdonotmatch theFilter criteria,ratherthanthepackagesthatdomatch.
ClickSubmit.Onlythepackageswhichmatchthefilteroptionswillbedisplayed. Filtering packages from an already filtered Package List
1 2
FilterthePackages Listasdescribedinthepreviousprocedure.Thepackageswhich matchthefilterwillbedisplayed. EnabletheFilter on resultmode.Thislimitsthesearchtojustthecurrentlydisplayed listofpackages,ratherthanthedefaultlistofallthepackagesontheserver. Note: YoucanalsoenabletheExclude from resultoptiontodisplaythepackagesthat donotmatchtheFiltercriteria,ratherthanthepackagesthatdomatch.
EnterthenewfiltercriteriaandclickSubmit.Repeatasmanytimesasnecessary,being suretoenabletheFilter on resultmodeeachtime.
282
Determining Whether the Server Successfully Loaded the Package

TheserverdisplaysastatusintheLoaded? columnofthePackagesscreen. Status Yes Indicates that Theserversuccessfullyloadedallelementsassociatedwiththepackage. Theelementsinthepackageareavailable.Theserveralsodisplaysthis statusifthepackageisempty. Theserverdidnotloadoneormoreoftheelementsassociatedwiththe package.Theelementsthattheserversuccessfullyloadedareavailable. Forinstructionsonhowtodeterminewhichelementstheserverdidnot successfullyloadandwhy,seeDisplayingInformationabouta Packageonpage 284. Theserverdidnotloadanyoftheelementsassociatedwiththepackage. Noneoftheelementsareavailable.Forinstructionsonhowtodetermine whytheservercouldnotloadtheelements,seeDisplayingInformation aboutaPackageonpage 284.
Partial
No
Whentheserverisstarted,itautomaticallyloadsintomemoryallelementsthatarein enabledpackages.Ifapackageisdisabledatstartup,theserverloadstheelementsinto memorywhenthepackageisenabled.Youcanmanuallyreloadapackageifnecessary. Forinstructionsonreloadingapackage,seeReloadingaPackageonpage 289.
Determining Whether the Package Is Enabled or Disabled

TheserverdisplaysastatusintheEnabledcolumnofthePackagesscreen.Thestatus indicateswhetherthepackageisenabledordisabled.Apackagemustbeenabledbefore theserverallowsclientsaccesstotheservicesinthepackage. Status Yes No Warnings Indicates that Thepackageisenabledandclientscanaccesstheelementsinthe package. Thepackageisdisabledandclientscannotaccesstheelementsinthe package. Someoftheelementsinthepackageencounteredwarnings,butwere loadedandareavailableforuse.Tolearnwhichelementscaused warnings,lookattheLoadWarningslistatthebottomofthescreen.
Forinstructionsonenablinganddisablingpackages,seeEnablingaPackageon page 290andDisablingaPackageonpage 290.
283
Displaying Information about a Package

ThePackages > Management > PackageNamescreendisplaysthefollowinginformation aboutapackage: Theversionnumberofthepackage.Bydefault,theDeveloperassignsversion1.0toa newpackage.Youcanassignanewversionnumbertothepackagewhenyourelease it. Thebuildnumberofthepackage.Thebuildnumberisakindofgenerationnumbera developerassignstoapackageeachtimeitisregenerated.Forexample,adeveloper mightgenerateversion1.0oftheOrderingpackage10timesandassignbuild numbers1,2,310tothedifferentgenerationsofthepackage. TheminimumversionofJVMrequiredtorunthepackage. NameofAccessControlList(ACL)thatcontrolswhichuserscanlistthepackage. ThisACListheonlyonepassedalongwithapackagewhenitispublished. Alistofpatchesincludedinthepackage. Abriefdescriptionsuppliedbythedeveloperwhocreatedthepackage. Howmanyelementsinthepackageareloadedintheserversmemoryandaccessto thelistoftheseelements. Howmanyelementsinthepackagearenotloadedintheserversmemory,alistof theseelements,andthereasonwhytheservercouldnotloadthem. Thelistofstartup,shutdown,andreplicationservicesinthepackage. Packagedependencies(packagesonwhichthispackagedependsandpackagesthat dependonthispackage). Thelistofsubscriberstothispackage. Patchhistory. To display information about a package 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuoftheNavigationpanel,clickManagement. InthePackage Listareaofthescreen,clickonthenameofthepackageforwhichyou wanttodisplayinformation. TheserverdisplaysthePackages > Management > PackageName screen,whichcontains thefollowingfields: Field Package Name Version Description Nameofthepackage. Versionnumberofthepackage.
284
Field Build
Description Anumberthatadeveloperassignstoapackageeach timeitisregenerated.Forexample,adevelopermight generateversion1.0oftheOrderingpackage10times andassignbuildnumbers1,2,3,10.Thesebuild numbersaregenerallyusedtoidentifythegenerationsof apackageinadevelopmentenvironment. MinimumversionoftheJavaVirtualMachine(JVM) requiredtorunthispackage. TheAccessControlListassignedtothepackage.Users associatedwiththisACLcanseethepackagelistedon theIntegrationServerAdministratorortheDeveloper. Toseethefoldersandelementscontainedinthepackage, ausermusthaveListaccesstothefoldersandelements themselves. Alistofpatchesthathavebeenappliedtothisreleaseof thepackage.Thesearenumbersthataremeaningfulto yourinstallation,possiblyobtainedfromyourproblem trackingsystem. Adescriptionofthepackageanditsintendeduse. Thenameofthecompany,organization,orserverthat publishedthepackage. Note: Bydefault,theIntegrationServerautomatically entersthepublishingservernameinthisfieldonlywhen youcreateapackagerelease.
Minimum Version of JVM Package List ACL
Patches Included
Description Publisher
Created on
Date,time,andyearinwhichthepackagewascreated. Note: Bydefault,theIntegrationServerautomatically entersthedate,time,andyearinthisfieldonlywhenyou createapackagerelease.
Elements Loaded
Numberofelementsthattheserversuccessfullyloaded. Toviewtheelementsthattheserverhassuccessfully loaded,clicktheBrowse services in <PackageName> link. Numberofelementsthattheserverfailedtoload.Ifthe serverfailedtoloadoneormoreelements,theLoad Errors sectionofthescreenliststheelementsthatitcouldnot load,alongwiththereason.
Elements Not Loaded
285
Field Startup Services
Description Listoftheservicesthatyouoranotheradministrator haveidentifiedasstartupservices.Formoreinformation aboutstartupservices,refertoRunningServicesWhen PackagesAreLoaded,Unloaded,orReplicatedon page 337. Listoftheservicesthatyouoranotheradministrator haveidentifiedasshutdownservices.Formore informationaboutshutdownservices,seeRunning ServicesWhenPackagesAreLoaded,Unloaded,or Replicatedonpage 337. Listoftheservicesthatyouoranotheradministrator haveidentifiedasreplicationservices.Formore informationaboutreplicationservices,seeRunning ServicesWhenPackagesAreLoaded,Unloaded,or Replicatedonpage 337. Listofthepackagestheservermustloadbeforeitloads thispackage.Formoreinformationaboutpackage dependencies,seethewebMethodsDeveloperUsersGuide. Listofpackagesthatdependonthispackage.Ifyou disablethepackage,thesepackageswillbeaffected. ListofotherIntegrationServersthatsubscribetothis package.Forinformationonhowtocopypackagesfrom oneservertoanother,howtosubscribetopackages,and howtopublishpackagestoanotherserver,seeCopying PackagesfromOneServertoAnotheronpage 292. Displaysalistofelementsthatgeneratederrorsand couldnotbeloadedontotheserverwhenthepackage wasinstalled.Whensomeelementsdonotload,theload statusforthepackagebecomesPartial. Displaysalistofelementsthatgeneratedwarningswhen thepackagewasinstalled.Theserverwasabletoloadthe packages,despitethewarnings.Whenpackageelements areloadedwithwarnings,theloadstatusforthepackage becomesWarnings. Alistofpatchesorpartialpackagesthathavebeen appliedtothisreleaseofthepackage.
Shutdown Services
Replication Services
Packages on which this package depends Packages that depend on this package Subscribers
Load Errors
Load Warnings
Patch History
286
Displaying Information about Services and Folders in a Package

Youcanbrowsealistofservicesorfoldersinapackage.SeeFindingInformationabout ServicesandFoldersonpage 334.
Displaying Documentation for a Package

YoucandocumentthefunctionofapackageanditselementsinWebdocumentsthatthe IntegrationServerwillserve.PlacetheWebdocumentsinthepubsubdirectoryfora package. Besuretocreateanindex.htmlfilethatholdsthehomepageforthepackageandcontains linkstotheotherWebdocumentsforthepackage. To access the home page for a package 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuoftheNavigationpanelclickManagement. Clickthehome iconforthepackage.
To access any Web document for a package Makesurethepackageisenabled.(SeeDeterminingWhetherthePackageIsEnabledor Disabledonpage 283forinstructions.)EntertheURLfortheWebdocument.TheURLs fortheWebdocumentshavethefollowingformat: http://host:port/PackageName/Docname where: host:port PackageName istheservernameandportaddressoftheIntegrationServer isthenameofthepackageinwhichtheWebdocumentresides.Ifyou donotspecifyapackagename,theserverlooksinthePubdirectoryof theDefaultpackage. isthenameoftheWebdocument.Ifyoudonotspecifyadocument name,theserverdisplaystheindex.dsporindex.htmlfileinthePub directoryofthespecifiedpackage.
DocName
287
Working with Packages

Youcanperformthefollowingtasksthatactonallthefilesinapackageasaunit: Use this function: Create When you want to: Createanewpackage.Developerscreatepackagesfromthe Developer.SeethewebMethodsDeveloperUsersGuideformore information. Useapackagethatyoumanuallymovedintothe Server/packagesdirectorywithouthavingtorestarttheserver. Reloadtheservicesinthepackageintomemorywithouthaving torestarttheserver. Enableapackagethatyoupreviouslydisabled. Disableaccesstoapackagewithoutdeletingit. Deleteallservicesandrelatedfilesinapackage. Recovertheservicesandrelatedfilesfromapackagethatyou previouslydeleted.Youcanonlyrecoveradeletedpackageif youhadtheserversaveacopyofthepackagebeforedeletingit. Makeaworkingcopyofapackagewithoutmakingitgenerally availabletoothersthrougharelease.Youmightusethiscopyas abackup. Copyapackagefromoneservertoanother. Refer to page: 288
Activate Reload Enable Disable Delete Recover
289 289 290 290 291 291
Archive
292
Copy
292
Note: Youcanalsomanagepackagesbyusingasetofbuiltinservices.Seethe webMethodsIntegrationServerBuiltInServicesReferenceformoreinformation.
Creating a Package
Whenadeveloperwantstocreateanewgroupingforservicesandrelatedfiles,heorshe createsapackage.Thiscreatesanemptycontainerintowhichyourdeveloperscanstore services,andrelatedfiles.Whenadevelopercreatesapackage,theserverbuildsthe directorystructureofthepackageasdescribedinHowtheServerStoresPackage Informationonpage 277.SeethewebMethodsDeveloperUsersGuideforinstructionson creatingaPackage.
288
Activating a Package
Theremaybetimeswhenapackageisinstalledonyourserverbutisnotactive.Whena packageisactive,itisofficiallyrecognizedbytheserveranddisplayedinthePackage List onthePackage Managementscreen.Whenapackageisinactive,itexistsinthePackages directory,butisnotofficiallyrecognizedbytheserver. Possiblereasonsforapackagebeinginactiveare: Youmanuallyinstalledthepackagewhiletheserverwasrunning. Anotherserverpublishedthepackagetoyourserver,butthepackagerequiresa versionoftheJVMthatishigherthantheversiononyourserver.Asubscribingserver willnotactivateapackageunderthesecircumstances. Thepackagewillnotbeavailableuntileitheryourestarttheserveroryouactivatethe package. To activate a package 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuoftheNavigationpanel,clickManagement. ClickActivate Inactive Packages. IntheInactive Packagesarea,selectthepackageyouwanttoactivatefromthepull downmenuandclickActivate Package.
Reloading a Package
IftheserverisrunningwhenadeveloperchangesaJavaserviceorflowservice,youmust reloadthepackageinwhichtheserviceiscontainedforthechangestotakeeffect. ReloadingthepackageinvokestheVMclassloadertoreloadthepackagesJavaservices andreloadstheflowservicesintomemory.Developerscanalsoreloadapackagefrom theDeveloper. To reload a package 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuoftheNavigationpanel,clickManagement. Clickthereloadicon intheReloadcolumnforthepackage.
The iconintheLoaded?columnindicateswhethertheserverloadedthepackage successfully.Formoreinformation,seeDeterminingWhethertheServerSuccessfully LoadedthePackageonpage 283.
289
Enabling a Package
Toallowclientsaccesstotheelementsinapackage,youmustensurethepackageis enabled.Beforetheservercanaccessanelementinapackage,thepackagemustbe enabledandtheelementmustbeloaded.Bydefault,packagesareenabled. Whenyouenableadisabledpackage,theserverloadstheelementsinthepackageinto memory. To enable a package 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuoftheNavigationpanel,clickManagement. ClickNointheEnabledcolumnforthepackageyouwanttoenable.Theserverissuesa prompttoverifythatyouwanttoenablethepackage.ClickOKtoenablethepackage. Whenthepackageisenabled,theserverdisplaysa column. iconandYesintheEnabled
Disabling a Package
Whenyouwanttotemporarilyprohibitaccesstotheelementsinapackage,disablethe package.Whenyoudisableapackage,theserverunloadsallofitselementsfrom memory. Important! NeverdisabletheWmRootpackage.TheIntegrationServerusesthe servicesinthispackage. To disable a package 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuoftheNavigationpanelclicktheManagementlink. Clickthe iconintheEnabledcolumnforthepackageyouwanttodisable.The serverissuesaprompttoverifythatyouwanttodisablethepackage.ClickOKto disablethepackage.Whenthepackageisdisabled,theserverdisplaysNointhe Enabledcolumn. Note: Theserverretainstheaccessstatusofapackage(enabledordisabled)across serverrestarts.Whenyoustarttheserver,theserverdoesnotloadelementsin disabledpackages.
290
Deleting a Package
Whenyounolongerneedtheservicesandfilesinapackage,youcandeletethepackage. Whenyoudeleteapackage,alltheelementsofthepackage(services,specifications, documenttypes)becomeunavailable. Whenyoudeleteapackage,youcanoptionallyselecttosaveacopyofthepackage.If yousaveacopy,theservercopiesthepackagetothe IntegrationServer_directory\replicate\salvagedirectorybeforedeletingthepackagefrom theIntegrationServer_directory\packagesdirectory.Ifneeded,youcanrecoverthe packageatalatertime.Forinstructionsonrecoveringadeletedpackage,seeRecovering aPackageonpage 291. Important! NeverdeletetheWmRootpackage.TheIntegrationServerusestheservices inthispackage. 1 2 3 4 5 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuoftheNavigationpanelclickManagement. Ifyouwanttosaveacopyofthepackagesoyoucanrecoveritlaterifnecessary,check the iconintherowthatcorrespondstothepackageyouwanttodelete. iconintherowthatcorrespondstothe
Ifyoudonotwanttosaveacopy,clickthe packageyouwanttodelete.
ClickDelete.Theserverdisplaysascreentoconfirmyouwanttodeletethepackage. ClickOK.
Recovering a Package
IfyoudeletedapackageusingtheSafe delete optionandyouneedthepackageagain,you canrecoverthepackage. To recover a package 1 2 3 4 5 6 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuoftheNavigationpanelclickManagement. ClickRecover Packages. IntheRecover Packagesarea,selectthepackageyouwanttorecoverfromthepull down. IfyouwanttheIntegrationServertoautomaticallyactivatethepackagewhenitis recovered,selecttheActivate Upon Recovery checkbox. ClickRecover.
291
Archiving a Package
Theremaybetimeswhenyouwanttomakeacopyofapackagewithoutmakingit generallyavailable.Forexample,youmightwanttobackituporsendittosomeonewith whomyoudonothaveapublisher/subscriberrelationship. To archive a package 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuoftheNavigationpanel,clickManagement. LocatethepackageyouwanttoarchiveinthePackage List,andclickthe icon.
Theserverdisplaysascreenfromwhichyouspecifythefilesyouwanttoarchive,the typeofarchive(fullorpatch),andversioninformation.SeeSpecifyingFileand VersionInformationforaReleaseorArchiveonpage 305forinstructionson specifyingthisinformation.
Copying Packages from One Server to Another

Usepackagereplicationtocopy(publish)packagesfromoneIntegrationServerto another.Ifyouhaveaclusteredenvironment,thisfeatureisusefultoquicklyreplicate newandupdatedpackagesacrossallserversinthecluster.Itisalsoaconvenientwayto distributeapackagefromoneservertoanotheranywhereontheWeb. Note: UsingwebMethodsDeveloper,youcancopyapackageanditscontentsto anotherIntegrationServerbyperformingacopyoradraganddropaction.Copying packagesusingDeveloperprovidesaquickwaytotestasetofservicesandtheir supportingfiles,forexample,inaremoteenvironment.Thismethodisusefulin singledevelopmentenvironmentswherechangecontrolisnotcrucial.Ina productionenvironment,however,usingthepackagereplicationfunctionis recommended. Note: Ifyouwanttomakeacopyofpackage,forexampletomakeabackup,without sendingittoanotherserver,seeArchivingaPackageonpage 292.
292
Overview of Package Replication

Duringreplication,asingleIntegrationServersends(publishes)aspecifiedpackageto oneormorerecipientservers.Theserveronwhichthepackageoriginatesisreferredtoas thepublisher,andtherecipientsarereferredtoassubscribers.
...a publishing server copies one package...

Publisher
...to one or more subscribing servers.
Subscriber
webMethods Integration Server webMethods Integration Server
Subscriber
Subscriber
Subscribingserversreceivethepackageintheirinbounddirectory (IntegrationServer_directory\replicate\inbound).Toactivatethenewpackage,an administratoronthesubscribingservermustinstallthepackageafteritarrives.(This procedureisexplainedinInstallingaPackagePublishedbyAnotherServeron page 316.) Eitherapublisherorasubscribercanrequestasubscription.Apublishercansend(push) thepackageandthesubscribercanrequest(pull)thepackage. Beforeyousendapackagetoanotherserver,youmustcreatearelease.Whenyoucreatea release,theservercreatesadistributionfilethatcontainsthepackageandinformation aboutthepackage,andmakesthepackageavailabletosubscribers. Youcanhavemultiplereleasesforagivenpackage.Forexample,youmighthave separatereleasesforversions1.0,1.1,and1.2ofagivenpackage.Or,youmightuse differentreleasestoseparatepackagesfordifferentaudiences.Eachreleasemusthavea uniquename.
293
Important! Ifyouhavemultiplereleasesofagivenpackageandoneormore subscribershavespecifiedtheautomaticpullfeature,thosesubscriberswillreceiveall releasesofapackagewhenanewreleaseofitbecomesavailable.Formore informationabouttheautomaticpullfeature,seeTheSubscribingServeron page 308. Areleasecancontainthecompletepackage(afullrelease)orjustpatchestothepackage (apatchrelease).Typicallyyouwillpublishafullreleasewhenyouhavemademajor changestothepackageandusepatchesjusttocorrectproblemswithapackage. Withafullrelease,thenewpackageentirelyreplacestheoldpackageonthesubscribers server.Withapatchrelease,thefilesinthepatchreleasereplacetheversionsofthosefiles inthetargetpackage;allotherfilesinthetargetpackageremainintact. Inadditiontospecifyingafullorpatchrelease,youcanselectallfilestogointherelease orjustsome. Thefollowingdiagramillustrateshowapatchreleasereplacesfiles:
Publishing Server Target Server before Patch Replication Target Server after Patch Replication
Package
Service A
Package
Service A
Package
Service A
Service B
Service B
Service B
Service C
Service C
Service C
* Select for replication
294
Thefollowingdiagramillustratestheresultsifyouselectedasingleservicefor replicationandspecifiedafullreleaseinstead.
Publishing Server Target Server before Full Replication Target Server after Full Replication
Package
Service A
Package
Service A
Package
Service B
Service B
Service B
Service C
Service C
* Select for replication

Mostoftenyouwillselectallfilesandspecifyafullrelease,orselectsomefilesand specifyapatchrelease.Theremightbetimeshoweverwhenyouwanttoselectjustsome filesandspecifyafullrelease.Forexample,theremightbefilesinapackage,suchas internaldocumentationfiles,thatadeveloperdoesnotwantreleasedtoothers.Selecting allfilesexcepttheextraneousonesandspecifyingafullreleaseresultsinapackagethat containsjustthedesiredfiles. Theremightbeothertimeswhenyouwanttoreplacesomefiles,leaveothersintact,and deleteothers.Toachievethisgreaterlevelofcontrol,youcanperformapatchreleaseand specifyfilestocopyandfilestodelete.Filesthatyoudonotspecifyforcopyingor deletionremainintact.Inthefollowingexample,wewanttoleaveServiceAintact, replaceServiceB,anddeleteServiceCfromthetargetpackage.
295
Publishing Server
Target Server before Patch Replication
Target Server after Patch Replication
Package
Service A
Package
Service A
Package
Service A
Service B
Service B
Service B
Service C
* Select B for replication and C for deletion

ThefollowingshowswhatyoumustspecifyontheSpecify Files for the Releasescreento accomplishthistask:
Select these files. They will replace the versions in the target package.
Click Selected Files.
Type in these files. They will be deleted from the target package.
TheIntegrationServerkeepstrackofpackageversions,IntegrationServerversions,and JVMversionssothatduringpackageinstallationthesubscribingservercanmakesure thepackagebeinginstallediscompatiblewiththesubscribingserversenvironment.The
296
typeofversioncheckingperformeddependsonwhetherthereleaseisafullorpatch release. Note: Ifpatchreleaseshavebeenappliedtoapackage,thedevelopercanseethepatch historywhenviewingthepackagefromtheDeveloper.However,whenthepublisher publishesafullreleaseofthepackage,thepatchhistoryisremoved.
Version Checking
Whentheadministratoronthesubscribingserverinstallsthepackage,thesubscribing serverperformssomeversionchecking: Target server verifies that Target JVM Version ThetargetserverisrunningthesameoralaterversionoftheJVM,as specifiedduringreleasecreation.Ifthisrequirementisnotmet,the subscribingserverissuesawarningandinstallsthepackagebutdoesnot activateit.SeeActivatingaPackageonpage 289forinstructionson activatingapackage. For a full release Theversionofthepackageonthe targetserverisearlierthanorthe sameasthepackagebeing installed.Ifthisrequirementisnot met,packageinstallationfails. Forexample,ifyoucreateanew releaseandspecifythatitcontains Version2.0ofthewmExample package,thewmExamplepackage onthetargetsystemmustbe release2.0orearlier. Thisrestrictionpreventsyoufrom inadvertentlyinstallinganold versionofapackageoveranewer one For a patch release Theversionofthepackageonthe targetserverexactlymatchesthe versionrequiredbytherelease(as specifiedduringreleasecreation).If thisrequirementisnotmet,package installationfails. Forexample,ifyoucreateanew releasethatcontainsapatchfor wmExamplepackageversion2.0, andyouspecifythatthetarget packagemustbeversion2.0, packageinstallationwillfailifthe targetpackageisnotversion2.0. Thisrestrictiongivesyougreater controloverhowandwherepatches areapplied.Thisisusefulbecause patchesaretypicallyrelease dependent.
Package Version
297
Who Can Subscribe?

AnyIntegrationServercansubscribetoapackageonanotherserverifbothserversallow itfromasecurityperspective. Securityforpackagereplicationisaccomplishedanumberofways: Userid and password. Inordertosendapackagetoasubscriber,thepublishermust logintothesubscriberbyspecifyingauseridandpasswordthatexistonthe subscriber. ACLs. Theuseridthepublisherusestologontothesubscribermustbeamemberofa groupthatisassignedtotheReplicatorsACLorhigheronthesubscriber. SSL. Youcanspecifythattheserversinvolvedinpackagereplicationconnecttoeach otherusingSSL. Thepublishermaintainsalistofsubscribingserversforeachpackage. Subscriptionscanbeaddedbythepublisherorthesubscriber: Publisher.Theadministratorofapublishingservercanusethepublisherfunctionsto add(orremove)subscriberstoanypackagethatoriginatesonthepublishingserver (i.e.,onetowhichyoudonotsubscribe). Subscriber.TheadministratorofaremoteIntegrationServer(thesubscriber)can submitasubscriptionrequesttothepublisher.Whenthepublisherreceivesthis request,itautomaticallyaddsthatservertothesubscriptionlistfortherequested packageaslongasauthenticationwassuccessful.Subscriberscanalsoissue cancellationrequests(i.e.,canceltheirsubscriptions)forpackagestowhichthey subscribe.
Guidelines for Using Package Replication

Keepthefollowingguidelinesinmindwhenusingthepackagereplicationfacility: PublishersandparticipatingsubscribersmustuseIntegrationServerVersion2.0or later.FortheforAutomaticPullfeaturetowork,theymustberunningVersion4.0or later.Ifyouarerunningversion4.0orlateroftheIntegrationServerandpublishtoan earlierreleaseoftheIntegrationServer,thesubscribercannotperformamanualor automaticpullofapackage.Instead,thesubscribermustwaitforthepublisherto sendthepackage AnyIntegrationServercanpublishapackage. AnyIntegrationServercansubscribetoapackageonanotherIntegrationServer.
298
AnIntegrationServercanbebothapublisherofpackagesandasubscriberofother packages;however,itcannotbebothapublisherandasubscriberofthesame package. Aftersettingupasubscription,ifyoudeletetheuseraccountwithwhichthe subscriptionwassetup(theaccountonthesubscribingserverthatthepublishing serverusestologon),thepublisherwillnotbeabletologintothesubscribingserver tosendthispackage.
The Publishing Server

Thissectiondescribesthetasksyouperformwhenyourserverisparticipatinginpackage replicationasthepublishingserver: Task: Displayingthelistofsubscribersforapackage Specifyingsubscribersforapackage Updatingsubscriberinformation Removingsubscribersforapackage Publishingapackagetosubscribingservers SpecifyingFileandVersionInformationforaReleaseorArchive Refer to page: 299 300 301 303 303 305
Displaying Subscribers
Usethisproceduretodisplaythelistofsubscribersforaspecificpackageonyourserver. To display the subscribers for a single package 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuoftheNavigationpanel,clickManagement. Clickthenameofthepackageforwhichyouwanttoviewsubscribers. TheserverliststhesubscriberstothepackageintheSubscribersfield. To display the subscribers for all packages 1 2 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuoftheNavigationpanel,clickPublishing. Theserverdisplaysalistofallpackages,theirsubscribers,andreleases.
299
Adding Subscribers from a Publishing Server

Whenyouaddasubscriber,youareidentifyingtheIntegrationServersthataretoreceive apackage.Youcanhaveadifferentlistofsubscribersforeachpackageonyourserver. Specifythesubscribers(recipients)ofthepackage.(Youonlyneedtoexecutethistaskthe firsttimeyoupublishthepackage;fromthenon,youcansimplymodifyorreusethe initiallist.) Note: Thefollowingprocedureisforaddingasubscriberfromapublishingserver.If youwanttorequestasubscriptionfromasubscribingserver,seeSubscribingtoa PackagefromaSubscribingServeronpage 310. To add a subscriber 1 2 3 4 5 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuoftheNavigationpanel,clickPublishing. ClickAdd Subscribers. Selectthepackageforwhichyouwanttoidentifysubscribersfromthedropdownlist inthePackagefield. Toidentifyasubscribingserver,enterinformationinthefollowingfields: Field Host Name Host Port Transport Description Nameofthemachineonwhichthesubscribingserveris running. Portnumberonwhichthesubscribingserverlistensforthis packagetobepublished. Methodthepublishingserverusestosendthepackagetothe subscribingserver.SelectHTTPorHTTPS.HTTPisthe default. Note: IfyouwantthepublishertouseSSLwhensendingthe packagetothesubscriber,youmustspecifyHTTPShere. Whenthepublisherconnectstothesubscriber,thepublisher usestheserversdefaultOutbound SSL Certificatesasspecified onthepublishersSecurity > Certificatesscreen. Remote User Name Userthepublishingserverusestologintothesubscriber server.Thisusermustbeamemberofagroupthatisassigned totheReplicatorsACLonthesubscribingserver.
300
Field Remote Password Notification Email
Description Passwordoftheuserthatthepublishingserverusestolog intothesubscribingserver. Emailaddressoftheadministratortonotifywhenthe publishingserverreleasesapackage.
Then,clickAdd Subscriber.TheserveraddsthesubscribertothelistintheSubscribers field. Repeatthisstepforeachserveryouwanttoidentifyasasubscribertothepackage. Note: Tospecifytheautomaticpullfeature,youmustcreatethesubscriptionfrom thesubscriber. Note: Thesubscribingservermustberunningatthetimeyouaddthesubscriber.
Updating Subscriber Information

Usethisproceduretoupdateinformationaboutasubscriber,suchasthepackagename. To update subscriber information 1 2 3 4 5 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuofintheNavigationpanel,clickPublishing. ClickUpdate and Remove Subscribers. LocatethissubscriberinthesubscriberinformationlistandclickEditintheUpdate column. Tochangesubscriberinformation,enterinformationintheappropriatefieldsbelow: Field Packages Description Packagestowhichthesubscribersubscribes.Youcanchangethe subscriptiontobeforanotherpackage.Youcanonlyselecta packagetowhichyourserverdoesnotalreadysubscribebecause youcannotbothpublishandsubscribetothesamepackage. Nameofthemachineonwhichthesubscribingserverisrunning. Portnumberonwhichthesubscribingserverlistensforthis packagetobepublished.Thenumberyouspecifymust correspondtoaportthatalreadyexistsandisenabledonthe subscribingserver.Inaddition,thepublishingservermusthave replicatoraccessorhigher.
Host Name Host Port
301
Field Transport
Description Methodthepublishingserverusestosendthepackagetothe subscribingserver.SelectHTTPorHTTPS.HTTPisthedefault. Thetransporttypemustmatchthetypedefinedforthehostport onthesubscribingserver. Note: IfyouwantthepublishertouseSSLwhensendingthe packagetothesubscriber,youmustspecifyHTTPShere. Whenthepublisherconnectstothesubscriber,thepublisheruses theserversdefaultOutbound SSL Certificatesasspecifiedonthe publishersSecurity > Certificatesscreen.
Remote User Name Remote Password Notification Email 6
Userthepublishingserverusestologintothesubscriberserver. Thisusermustbeamemberofagroupthatisassignedtothe ReplicatorsACLonthesubscribingserver. Passwordoftheuserthatthepublishingserverusestologinto thesubscribingserver. Emailaddressoftheadministratortonotifywhenthepublishing serverreleasesapackage.
Then,clickSubmit Changes.TheserveraddsthesubscribertothelistintheSubscribers field.Theserverupdatestheinformationonboththesubscribingandpublishing servers.
302
Removing Subscribers for a Package

Usethisproceduretoremoveasubscriberfromapackagethatyoupublish. Note: Ifasubscriberremovesasubscriptioninitiatedbythepublisher,the subscribingserverremovesthesubscriptionfromitssubscriptionslist,butthe subscriptionisnotimmediatelyremovedfromthepublisherslist.Instead,the nexttimethepublishingservertriestosendthepackagetothesubscriber,the publisherisnotifiedoftheremovalandthendeletesthesubscriptionfromthe publisherslist. To remove subscribers 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuofintheNavigationpanel,clickPublishing. ClickRemove Subscribers. Locatethepackageforwhichyouwanttoremovesubscribersandchecktheboxin theDeletefield. Note: Ifthesubscriberisrunningwhenyouremoveitfromthesubscriberlist,the publishertellsthesubscriberithasbeenremoved.However,ifthesubscriberisnot running,thesubscriberwillnotknowthesubscriptionhasbeencanceled.Inthiscase, youshouldmanuallydeletethesubscriptionfromthesubscriberserverlaterwhenit isavailable.
Publishing a Package
PublishingapackagetootherIntegrationServersinvolvestwotasks: Creating a release.Topublishapackage,yourservercreatesadistributionfilethat containstheinformationforthepackage. Whenyoucreatethedistributionfile,youselectwhatinformationtoincludeinthe file. Youcanselectallfilestosend,orjustsome.Inaddition,youcanrequestafullrelease orapatchrelease.Withafullrelease,thenewpackageentirelyreplacestheold packageonthesubscribersserver.Withapatchrelease,thefilesinthepatchrelease replacetheversionsofthosefilesinthetargetpackage;allotherfilesinthetarget packageremainintact.SeeOverviewofPackageReplicationonpage 293formore informationabouthowfullandpatchreleasesdiffer. Afteryouindicatethefilestoincludeintherelease,theserverplacesalltheselected filesintoasingle,compressedfile(azipfile).Itplacesthezipfileinthe IntegrationServer_directory\replicate\outbounddirectory.Iftheoutbounddirectory alreadycontainsazipfileforthispackage,theserveroverwritestheexistingfile.
303
Sending the release.Afteryoucreatetherelease,youcansendittothesubscribing servers. Asubscribingserverreceivesthezipfilecontainingthereleaseinitsinbound directory(IntegrationServer_directory\replicate\inbound).Ifazipfileforthepackage alreadyexistsinasubscribingserversinbounddirectory,theserveroverwritesit. Thezipfileremainsintheinbounddirectoryonthesubscribingserveruntilthe administratorofthatserverinstallsthepackage. Adevelopercansetupthepackagetoexecuteaservicewhenyoucreatetherelease. Whenyoubegintocreatetherelease,thisserviceexecutesbeforethelistoffilestobe zippedisdisplayed.Youcanusethisservicetowritestateandconfigurationinformation forthepackagetoafile.Thisfilewillbeincludedwiththeotherzippedfilesincludedin therelease.SeethewebMethodsDeveloperUsersGuideforinstructionsonsettingup replicationservices. Important! Beforeyoucanpublishapackage,youmustspecifythesubscribers.For instructions,refertoAddingSubscribersfromaPublishingServeronpage 300. To create a release 1 2 3 4 5 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuoftheNavigationpanel,clickPublishing. ClickCreate and Delete Releases. Locatethepackageforwhichyouwanttocreatearelease,andclickCreate Release for PackageName. Theserverdisplaysascreenfromwhichyouspecifythefilesyouwanttoincludein therelease,thetypeofrelease(fullorpatch),andversioninformation.See SpecifyingFileandVersionInformationforaReleaseorArchiveonpage 305for instructionsonspecifyingthisinformation. To send the release 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuoftheNavigationpanelclickPublishing. LocatethereleaseofthepackageyouwanttosendunderAvailable Releases,andclick Send Release.
304
Specifying File and Version Information for a Release or Archive

Whenyouarchiveapackageorcreatearelease,theserverdisplaysascreenfromwhich youcanspecifythefilesyouwanttoarchiveorrelease,thetypeofarchiveorrelease(full orpatch),andversioninformation. RefertoArchivingaPackageonpage 292fordetailedinstructionsonhowtoarchivea package.Also,refertoPublishingaPackageonpage 303fordetailedinstructionson howtocreateandsendarelease. To specify file and version information 1 Identifythefilesthatyouwanttoincludeintherelease/archive. If you want to include: Allfiles Most,butnotall,of thefiles Do this: IntheFiles to include section,selectAll files. IntheFiles available in package,section,selectthefilesyoudo NOTwanttoincludeinthearchiveorrelease. IntheFiles to include section,selectall except selected files. Ifthedeveloperaddedpackagedependenciesorstartup, shutdown,orreplicationservicestothepackagesincethe lastarchiveorreleasewascreated,besuretoincludethe manifest.v3file.Otherwisetheseserviceswillnotbe availableintheresultantpackage.SeeRunningServices WhenPackagesAreLoaded,Unloaded,orReplicatedon page 337formoreinformationaboutstartup,shutdown,and replicationservices. Onlyafewofthe files Inthe Files available in packagesection,selectthefilesyouwant toincludeinthearchiveorrelease. IntheFiles to include section,selectSelected files. Ifthedeveloperaddedpackagedependenciesorstartup, shutdown,orreplicationservicestothepackagesincethe lastarchiveorreleasewascreated,besuretoincludethe manifest.v3file.Otherwisetheseserviceswillnotbe availableintheresultantpackage.SeeRunningServices WhenPackagesAreLoaded,Unloaded,orReplicatedon page 337formoreinformationaboutstartup,shutdown,and replicationservices.
305
If you want to include: Fileswithasimilar pathname
Do this: IntheFiles to include section,selectFiles specified by filter and enteravalidfilter,forexample*.javaor*.class. or Toincludeallfilesexceptthosewithasimilarname,inthe Files to includesection,clickAll except files specified by filterand enteravalidfilter,forexample*.bak. Ifthedeveloperaddedpackagedependenciesorstartup, shutdown,orreplicationservicestothepackagesincethe lastarchiveorreleasewascreated,besuretoincludethe manifest.v3file.Otherwisetheseserviceswillnotbe availableintheresultantpackage.SeeRunningServices WhenPackagesAreLoaded,Unloaded,orReplicatedon page 337formoreinformationaboutstartup,shutdown,and replicationservices. Youcanspecifythefollowingspecialcharactertoperform patternmatching. Char * Description Matchesanynumberofcharacters Example *.java
Identifyfilesyouwanttodeletefromthetargetpackagebyenteringonefilenameper line.Separateeachentrywithasemicolon(;).Whenthesubscribingserverinstallsthe package,thesefileswillbedeletedfromthetargetpackage.
306
Specifypackageversioninformationanddescription: Field Archive/Release Type What It Means: Full:Allfilesinthepackagearewrittentothearchiveor release Patch:Selectedfilesinthepackagearewrittentothearchive orrelease.Whentheadministratoronthetargetserver installsapatcharchiveorrelease,thefilescontainedinthe patcharchiveorreleasereplacetheversionsofthosefilesin thetargetpackage;allotherfilesinthetargetpackage remainintact. Ifthedeveloperaddedpackagedependenciesorstartup, shutdown,orreplicationservicestothepackagesincethe lastarchiveorreleasewascreated,besuretoincludethe manifest.v3file.Otherwisetheseserviceswillnotbe availableintheresultantpackage.SeeRunningServices WhenPackagesAreLoaded,Unloaded,orReplicatedon page 337formoreinformationaboutstartup,shutdown, andreplicationservices. Archive/Release Name Brief Description Anameyouassigntothearchiveorrelease,forexample BetaReleaseofWmExamplePackage. Adescriptionyouassigntothearchiveorrelease,for exampleDecreleasewithpatchestocorrectOrderProcess problem. Theversionnumberyouassigntothepackageyouare archivingorreleasing.Thisversionmightnotbethesameas theversionofthepackageitself.Whenadeveloperfirst createsapackage,thewebMethodsDeveloperassigns version1.0toit. FormoreinformationaboutthecheckingtheIntegration Serverperforms,seeVersionCheckingonpage 297. Build Number Anumberthatadeveloperassignstoapackageeachtimeit isregenerated.Forexample,adevelopermightgenerate version1.0oftheWmExamplepackage10times,assigning buildnumber1,2,310. Alistofpatchesthathavebeenappliedtothisreleaseofthe package.Thesearenumbersthataremeaningfultoyour installation,possiblyobtainedfromyourproblemtracking system.
Version
Patches Included
307
Specifysubscribersettings: Field webMethods Integration Server What It Means: VersionofthewebMethodsserverthatmustberunningon thetargetserver. Formoreinformationabouttheversionchecking performedbythesubscribingserver,seeVersion Checkingonpage 297. Minimum Version of JVM MinimumversionoftheJavaVirtualMachine(JVM)that thetargetIntegrationServershouldberunningwhenusing thispackage.Whentheadministratorinstallsthepackage, theservercheckstheversionoftheJVMitisrunning.Ifitis runningadifferentversion,theserverinstallsthepackage butdoesnotactivateit. Formoreinformationabouttheversionchecking performedbythesubscribingserver,seeVersion Checkingonpage 297.
5 6
Specifyversionoftargetpackage(forpatchreleasesonly). Thisistheversionofthepackagethetargetservermustberunning.Whenthe administratorinstallsthepatchonthetargetserver,theservercheckstomakesure theversionofthetargetpackageisthesameastheonespecifiedhere.Ifthetarget packageisadifferentversion,theserverdoesnotinstallthepackage.Thisrestriction givesyougreatercontroloverhowandwherepatchesareapplied.Thisisuseful becausepatchesaretypicallyreleasedependent.
The Subscribing Server

Thissectiondescribesthetasksthesubscribingserverperformswhenparticipatingin packagereplicationasthesubscribingserver. Subscriberscanretrievepackagesmanuallyorautomatically.Toretrieveapackage manually,anadministratoronthesubscribingserverviewsalistofavailable subscriptionsandretrievesthedesiredpackage.Whenautomaticpullisineffect,the subscribingserverautomaticallypullsapackagefromthepublisherwhenanewrelease becomesavailable. Forapackagetoberetrievedautomatically,thesubscribermustspecifytheautomatic pullfeaturewhensettingupthesubscription.Whenanewreleasebecomesavailable,the publishingserversendsaserviceinvocationemailtoadesignatedemailserver.The serviceinvocationemailcontainsacalltoaservicethatrunsonthesubscribingserverto retrievepackages.Thesubscribingserverperiodicallycheckstheemailserverthroughan emailportonthesubscribingserver.Whenitreceivesandprocessestheservice invocationemail,thesubscribingserverautomaticallypullsthepackagefromthe
308
publisherandplacesitintheInbounddirectory.Theadministratoronthesubscribing servercantheninstallthepackage. Task: Displayingpackagestowhichyourserversubscribes ManuallyPullingaPackage Subscribingtoapackagefromanotherserver Updatingsubscriptioninformation Cancelingasubscriptiontoapackageonanotherserver Installingapackagethatwaspublishedfromanotherserver Refer to page: 309 309 310 313 315 316
Displaying Packages That Your Server Subscribes To

Youcanviewthesubscriptionsyourserverhastopackagesonotherservers. To display the packages to which your server subscribes 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuoftheNavigationpanelclickSubscribing. Theserverdisplaysalistofyouravailablesubscriptions,organizedbypublisher, package,andrelease.
Theserverautomaticallyupdatesthisinformationwhenyou(thesubscriber)add, update,orremoveasubscription;however,toseechangesmadebythepublishers,you mustclickUpdate All Subscription Details.
Manually Pulling a Package

Youcanmanuallypullsubscriptionstotheinbounddirectoryofyourserver. To pull a package you have already subscribed to 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuoftheNavigationpanel,clickSubscribing. Theserverdisplaysalistofyouravailablesubscriptions,organizedbypublisher, package,andrelease.
309
FindthereleaseofthepackageyouwanttopullandintheRetrievefield,clickthe retrievalmethodyouwanttouse. Field Via Service Invocation Via FTP Download What It Means: ThepublishingserversendsthereleaseusingHTTPorHTTPS. ThepublishingserversendsthereleaseusingFTP. WhenyouselectFTP,theserverpromptsyouforinformation requiredtouseFTP: Release Name:Nameassignedtotherelease,forexampleBeta ReleaseofWmExamplePackage. Remote Server Alias: Nameofthemachineonwhichthe publishingserverresides. Remote Server FTP Port:FTPportonthepublishingserver throughwhichthepublisherwillsendthepackage. Remote User Name: Userthatthesubscriberusestologintothe publishingserver. Remote Password: Passwordoftheuserthatthesubscribing serverusestologintothesubscribingserver.
Installthepackage.Forinstructions,seeInstallingaPackagePublishedbyAnother Serveronpage 316.
Subscribing to a Package from a Subscribing Server

Whenyousubscribetoapackagefromthesubscribingserver,yourserversendsa subscriptionrequesttothepublishingserver.Thepublishingserveraddsyourserverto thesubscriptionlistforthepackage. Theremoteservermusthaveanaliasdefinedonthelocalserver.Iftheremoteserver doesnotalreadyhaveanaliasdefined,youcandefineoneaheadoftimebygoingtothe SettingsmenuoftheNavigationpanelandclickingRemote Servers oryoucandefineone whilecreatingthesubscription. Whenrequestingasubscription,thesubscribermustprovidethefollowingtwoway connectioninformationtothepublisher: Method the subscriber will use to connect to the publisher to make the subscription request.The subscribermustsupplyavaliduseridandpassworditcanusetologontothe publishingserver.Yousetupthisandotherconnectioninformationusingaremote serveraliasforthepublisher. Method the publisher will use to connect to the subscriber when sending it a package.The subscribermustsupplyavaliduseridandpasswordthatthepublishercanusetolog ontothesubscribingserver.Thisuseridmustbeamemberofagroupthatisassigned
310
totheReplicatorsACL.Inaddition,thesubscribermustsupplyotherconnection information,suchaslisteningport. Thefollowingproceduresdescribehowtorequestasubscription. Note: Thefollowingprocedureisforaddingasubscriberfromasubscribingserver.If youwanttosetupasubscriptiononapublishingserver,seeAddingSubscribers fromaPublishingServeronpage 300. Important! Ifyourequestasubscriptiontoapackagethatdoesnotexistonthe specifiedserver,orifthatserverdoesnotownthepackage(i.e.,itisasubscriberof thepackage),youwillreceiveanerrormessage,andthepublishingserverdoesnot processyoursubscription. To subscribe to a package from another server 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuoftheNavigationpanel,clickSubscribing. ClickSubscribe to Remote Package. TypethenameofthepackageinthePackagefield.Besuretotypethenameexactlyas itisspecifiedonthepublishingserver,usingthesamecombinationofupperand lowercasecharacters. Entertheinformationinthefollowingfieldstosetupyourrequest: Field Publisher Alias Description Aliasassignedtothepublisher.Thealiasdefinitiontellsthe subscriberhowtoconnecttothepublishingservertoregisterfora subscription.Thealiascontainsconnectioninformationsuchas hostnameorIPaddress.Ifyouhavenotalreadydefinedanalias forthispublisher,clickthelinktogototheRemoteServers screen.Fromthisscreenyoucansetupanaliasforthepublisher. SeeSettingUpAliasesforRemoteIntegrationServerson page 68formoreinformation. Portnumberonwhichthesubscriberlistensforthepublisherto sendthepackage.Thissettingdetermineswhetherthepublisher usesHTTPorHTTPS. Important! IfyouwantthepublishertouseSSLwhensendingthe packagetothesubscriber,youmustspecifyanHTTPSporthere. Local Password Notification Email Passwordforthelocalusername. Emailaddresstonotifywhenthepublishingserverreleasesa packageorapackageisdelivered.
Local Port
311
Field Automatic Pull
Description Specifieswhetherthesubscribingserveristoautomaticallypull thepackagefromthepublisherwhenanewreleasebecomes available. IfyouselectYes,youmustalsospecifytheemailaddressofauser onanemailservertowhichthepublishingservershouldsenda serviceinvocationemail. Thesubscribingserver,throughanemailport,periodicallychecks thisemailaddressforaserviceinvocationemail.Whenthe subscribingserverprocessestheemail,itpullsthepackage. Theserviceinvocationemailcontainsacalltoaservicethatruns onthesubscribingserverandloadsthepackagetothe subscribingserversInbounddirectory. Forautomaticpulltowork,youmustsetupanemailportto listenattheautomaticpulladdress(describedbelow). Forinformationaboutsettingupanemailport,seeSettingUp AliasesforRemoteIntegrationServersonpage 68.
Automatic Pull Email
Emailaddresstowhichthepublishingserveristosendaservice invocationemailwhenanewreleaseofthepackagebecomes available. Useadifferentemailaddressforthenotificationandservice invocationemails.Forexample,sendnotificationemailsto package_notifications@mymailserver.comandserviceinvocation emailstopackage_autopulls@mymailserver.com. Forautomaticpulltowork,youmustsetupanemailportto listenatthisaddress. Forinformationaboutsettingupanemailport,seeSettingUp AliasesforRemoteIntegrationServersonpage 68.
Note: Thepublishingservermustberunningatthetimeyouaddthesubscription. 6 ClickStart Subscription.
312
Updating Your Subscription Information

Usethisproceduretoupdateinformationaboutyoursubscription,suchastheusername orpasswordonthesubscribingserver. To update your subscription information 1 2 3 4 5
?
OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuofintheNavigationpanel,clickSubscribing. ClickUpdate and Unsubscribe from Remote Package. ClickEditintheUpdatecolumnforthepackageyouwanttoupdate. Tochangesubscriptioninformation,enterinformationintheappropriatefields below: Field Package Description Packageforwhichyouwanttochangesubscription information. Youcanchangethepackagetoanotherpackageifyoudonot alreadysubscribetoorpublishthenewpackage.This restrictionexistsbecauseyoucannotbothsubscribetoand publishthesamepackage. Publisher Alias Aliasassignedtothepublisher.Thealiasdefinitiontellsthe subscriberhowtoconnecttothepublishingservertoregister forasubscription.Thealiascontainsconnectioninformation suchashostnameorIPaddress.Ifyouhavenotalready definedanaliasforthispublisher,clickthelinktogotothe RemoteServersscreen.Fromthisscreenyoucansetupanalias forthepublisher.SeeSettingUpAliasesforRemote IntegrationServersonpage 68formoreinformation. Portnumberonwhichthesubscriberlistensforthepublisherto sendthepackage.Thissettingdetermineswhetherthe publisherusesHTTPorHTTPS. Important! IfyouwantthepublishertouseSSLwhensending thepackagetothesubscriber,youmustspecifyanHTTPSport here. Note: Whenthepublisherconnectstothesubscriber,the publisherusesitsdefaultcertificate(specifiedonitsSecurity Settingsscreen).Makesuretheportyouspecifyherecanaccept thatcertificate.
Local Port
313
Field Local User Name
Description Useraswhichthepublisherwilllogintothesubscriber. Thisusermustbelongtoausergroupthatisassignedtothe ReplicatorsACL.Ifyoudeletetheuserorchangeitsassociation withtheReplicatorsACL,thepublishercannotsendthis packagetothesubscriber.
Local Password Notification Email Automatic Pull
Passwordforthelocalusername. Emailaddresstonotifywhenthepublishingserverreleasesa packageorapackageisdelivered. Specifieswhetherthesubscribingserveristoautomaticallypull thepackagefromthepublisherwhenanewreleasebecomes available. Ifyoualreadyhaveautomaticpullconfiguredandwanttoturn itoff,selectNo.ThengototheAutomatic Pull Emailfieldand deletetheemailaddressthere. IfyouwanttoconfigureyourserverforAutomaticPull,select Yes.Youmustalsospecifytheemailaddressofauseronan emailservertowhichthepublishingservershouldsenda serviceinvocationemail. Thesubscribingserver,throughanemailport,periodically checksthisemailaddressforaserviceinvocationemail.When thesubscribingserverprocessestheemail,itpullsthepackage. Theserviceinvocationemailcontainsacalltoaservicethat runsonthesubscribingserverandloadsthepackagetothe subscribingserversInbounddirectory. Forautomaticpulltowork,youmustsetupanemailportto listenattheautomaticpulladdress(describedbelow). Forinformationaboutsettingupanemailport,seeSetting UpAliasesforRemoteIntegrationServersonpage 68.
314
Field Automatic Pull Email
Description Emailaddresstowhichthepublishingserveristosenda serviceinvocationemailwhenanewreleaseofthepackage becomesavailable. Useadifferentemailaddressforthenotificationandservice invocationemails.Forexample,sendnotificationemailsto package_notifications@mymailserver.comandserviceinvocation emailstopackage_autopulls@mymailserver.com. Forautomaticpulltowork,youmustsetupanemailportto listenatthisaddress. Forinformationaboutsettingupanemailport,seeSetting UpAliasesforRemoteIntegrationServersonpage 68.
Note: Thepublishingservermustberunningatthetimeyouaddthesubscription. 6 7 ClickSubmit Changes. Theserverupdatestheinformationonboththesubscribingandpublishingservers.
Canceling a Subscription
Whenyoucancelasubscription,theserversendsyourcancellationnoticetothe publishingserver.Thepublishingserverremovesyourserverfromthesubscriptionlist forthespecifiedpackage.Ifthepublisherisnotrunningwhenyoucancelyour subscription,thenexttimethepublishertriestosendthepackagetoyourserver,the publisherisinformedofthecancellationandautomaticallydeletesthesubscriptionfrom itslistofsubscribers. Note: Ifasubscriberremovesasubscriptioninitiatedbythepublisher,thesubscribing serverremovesthesubscriptionfromitssubscriptionslist,butthesubscriptionisnot immediatelyremovedfromthepublisherslist.Instead,thenexttimethepublishing servertriestosendthepackagetothesubscriber,thepublisherisnotifiedofthe removalandthendeletesthesubscriptionfromthepublisherslist. To cancel your subscription to a package on another server 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuoftheNavigationpanel,clickSubscribing. ClickUpdate and Unsubscribe from Remote Package. Locatethepackageforwhichyouwanttocancelthesubscriptionandclickthe icon.
315
Installing a Package Published by Another Server

Whenanotherserverpublishesapackagetoyourserver,youneedtoinstallthe publishedpackage. Ifyouinstallapackagethathasthesamenameasanexistingpackageonyourserver, yourservercopiestheoriginalpackagetoIntegrationServer_directory\replicate\salvage beforeitinstallsthenewone.Thisletsyoueasilyreverttothepreviousversionifyouare dissatisfiedwiththenewpackage.Forinformationaboutrevertingtotheearlierversion, refertoRecoveringaPackageonpage 291. Youcanselectwhetheryouwanttheservertoimmediatelyactivatethepackageafterit installsit.Ifyoudonotselecttoactivatethepackage,theservercopiesthepackagetothe packagesdirectory,butitisnotavailableforclientstouse.Tomakethispackageavailable forclients,youmustmanuallyactivateit.Formoreinformation,refertoActivatinga Packageonpage 289. ApackagecomingfromthepublisheralreadyhasaListACLassociatedwithit, specifically,theListACLthatwasassignedtothepackageonthepublishingserver. TheinstallinguserdoesnotneedtobeamemberofthatACLtoinstallthepackage; however,usersonthesubscribingservermustbemembersofthepackagesListACLin ordertodisplaythepackageonIntegrationServerAdministratorscreens. Important! BesuretheserverwhereyouareinstallingthepackagehasanACLwiththe samenameaspackagesListACL.IftheListACLdoesnotexist,nouserswillbeable todisplaythepackageonIntegrationServerAdministratorscreens. Ifthepackageyouareinstallinghasdependenciesonanotherpackagethatdoesnotexist onyourserver,theserverwillinstallthepackagebutwillnotenableit.Youwillnotbe abletoenabletheinstalledpackageuntilthedependenciesaresatisfied. Ifthepackageyouareinstallingisassociatedwithanemaillistener,theserverwillinstall thepackagebutwillnotenablethelistener.Thisisbecausethepasswordrequiredforthe IntegrationServertoconnecttotheemailserverwasnotsentwithotherconfiguration informationaboutthelistener.Toenablethelistener,gototheSecurity > Ports > Edit Email Client ConfigurationScreenandupdatethePasswordfieldtospecifythepasswordneeded toconnecttotheemailserver. Ifyouexportapackagethatisassociatedwithanemaillistenerfroma6.5Integration Servertoapre6.5IntegrationServer,theemaillistenerwillnotbereplicatedatall.You mustmanuallyreconfigurethelisteneronthepre6.5IntegrationServerafterinstalling thepackagethere.Forinstructionsonconfiguringtheemaillistener,refertoAddingan EmailPortonpage 103. Important! Makesurethatpackagesyouinstallcomefromalegitimatesource,suchas areplicationfromanotherserver.Ifyouarenotsure,checkwiththedevelopersin yourorganizationtoverifythatanauthorizedpersonupdatedthepackage. Unknownpackagesmightcontaincodethatcoulddamageyourserver.
316
To install a package that was published from another server 1 2 3 4 5 6 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuoftheNavigationpanel,clickManagement. Click Install Inbound Releases. SelectthepackageyouwanttoinstallfromtheRelease file namedropdownlist. Ifyouwanttomakethepackageavailableimmediatelyfollowinginstallation,check theActivate upon installationcheckboxintheOptionfield. ClickInstall Release.
317
318
19
Caching Service Results

320 320 322 322
What Is Caching? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . When Are Cached Results Returned? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Resetting the Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Service Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
319
19 Caching Service Results
What Is Caching?
Cachingisanoptimizationfeaturethatcanimprovetheperformanceofservices. YouindicatetheservicesforwhichyouwanttousecachingfromthewebMethods Developer.Whenyouenablecachingforaservice,webMethodsIntegrationServersaves theentirecontentsofthepipelineafterinvokingtheserviceinalocalcachefortheperiod oftimethatyouspecify.Thepipelineincludestheoutputfieldsexplicitlydefinedinthe cachedservice,aswellasanyoutputfieldsproducedbyearlierservicesintheflow. Whentheserverreceivessubsequentrequestsforaservicewiththesamesetofinput values,itreturnsthecachedresulttotheclientratherthaninvokingtheserviceagain. Cachingcansignificantlyimproveresponsetimeofservices.Forexample,servicesthat retrieveinformationfrombusydatasourcessuchashightrafficcommercialWebservers couldbenefitfromcaching.Theservercancachetheresultsforalltypesofservices: flows,Javaservices,andC/C++services. Thegoalforcachingistostriketherightbalancebetweendataconcurrencyandmemory usage.Togaugetheeffectivenessofyourcache,youcanmonitoritsperformanceby viewingservicestatisticsfromtheIntegrationServerAdministratorandadjustyour cachingvaluesaccordingly. YousetthecontrolsforcachingaservicefromtheDeveloper.SeethewebMethods DeveloperUsersGuideformoreinformationonconfiguringaservicesuseofcache.
When Are Cached Results Returned?

WhenyouenablecachingforaserviceinthewebMethodsDeveloper,thewebMethods IntegrationServerhandlesthecachedresultsdifferently,dependingonwhetherthe servicehasinputparameters.Itisrecommendedthatacachedservicehasinput parameters. Service with input parameters.Whenacachedservicehasinputparameters,atruntime theIntegrationServerscopesthepipelinedowntoonlytheinputparametersofthe service.Thescopeddowninputsarecomparedtothepreviouslystoredcopyof inputs.Iftheyexistandmatch,thecachedresultsfromthepreviousservice invocationareused.
320
Pipeline Inputs Are Compared to the Cached Copy at Run Time

Pipeline At run time, the Integration Server scopes the pipeline down to only the input parameters of the service... Cached Service ...and compares them to the cached copy. If they match in name, dimension, and value, the cached output from the previous service invocation is used.
Service without input parameters. Whenacachedservicedoesnothaveinputparameters (forexample,adate/timeservice)andpreviousresultsdonotexistinthecache,atrun timetheIntegrationServerexecutestheserviceandstorestheresults.Whenthe serviceexecutesagain,thecachedcopyisused.Inotherwords,thepipelineisnot used;youwillalwaysreceivecachedresultsuntilthecacheexpires. Whenvariablesthataredefinedinthecachedservicesinputparametersaremissing fromthepipeline,theIntegrationServerextractsanyvariablesthatexistinthepipeline thatmatchthecachedservicesinputparameters.Ifnorequiredvariablesexistinthe pipeline,theIntegrationServerignoresthepipelineandessentiallyconsidersthatno inputparameterswereprovided. Important! Ifyoueditacachedservicebychangingtheinputs(notthepipeline),you mustresettheservercache.Ifyoudonotresetit,theoldcachedinputparameterswill beusedatruntime.ToresettheservicecachefromDeveloper,selecttheserviceand thenclicktheResetbuttonnexttoReset CacheinthePropertiespanel.Toresetthe servicecachefromIntegrationServerAdministrator,selectService UsageunderServer intheNavigationpanel.Selectthenameoftheserviceandaninformationscreenfor thatserviceappears.ClickReset Server Cache.
321
Resetting the Cache

Youcanresetthecacheforallservicesoryoucanresetthecacheforaspecificservice. Whentheserverresetsthecache,itremovesallcachedserviceresultsfrommemory. To reset the cache for all services 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheServermenuoftheNavigationpanel,click Service Usage. ClickReset Server Cachetoresetthecachesofallthelistedservices. To reset the cache for a specific service 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheServermenuoftheNavigationpanel,click Service Usage. Selectthenameoftheserviceforwhichyouwanttoresetthecache.Aninformation screenforthatserviceappears. ClickReset Service Cache.
Viewing Service Statistics

Usethefollowingproceduretomonitortheperformanceofyourcache. To monitor the performance of your cache 1 2 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheServermenuoftheNavigationpanel,clickService Usage. TheService Usagescreendisplaysthecurrentresultsofyourcachecontrolsettingsfor eachcachecontrolledservice. Tip! EnableShow running services on toptodisplayallthecurrentlyrunning servicesintheIntegrationServertogetheratthetopofthescreen.Currently runningservicesareidentifiedbyanumberinbracketsattherightoftheservice name.Thenumberidentifieshowmanyinstancesoftheservice,ifany,are currentlyrunning. DisableShow running services on toptorestorethelisttoalphabeticalorder.
322
20
Configuring Guaranteed Delivery

324 325 328 330
About Guaranteed Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring the Server for Guaranteed Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Administering Guaranteed Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying an E-Mail Address and SMTP Server for Error Messages . . . . . . . . . . . . . . . . . . . . .
323
20 Configuring Guaranteed Delivery
About Guaranteed Delivery

UsetheguaranteeddeliverycapabilitiesofthewebMethodsIntegrationServertoensure guaranteedonetimeexecutionofservices. ThewebMethodsIntegrationServerguaranteeddeliverycapabilitiesensurethatthe followingoccurdespitetransientfailures: Requeststoexecuteservicesfromclientsaredeliveredtotheserver Servicesareexecutedonce,andonlyonce Responsesfromtheexecutionoftheservicesaredeliveredtotheclient ThewebMethodsguaranteeddeliverycapabilitiesprotectagainsttransientfailuresthat mightoccuronthenetwork,intheclient,orontheserver.Atransientfailureisafailure thatcancorrectitselfduringaspecifiedperiodoftime.Ifarequestcannotbedeliveredto theserverduetoatransientfailure,therequestisresubmitted;iftheproblemhas correcteditself,therequestissuccessfullydeliveredonasubsequentattempt.You determinewhatconstitutesatransienterrorbyspecifyingatimetolive(TTL)periodfor aguaranteeddeliverytransactionand,optionally,thenumberoftimesatransaction shouldberetried. BecauseanIntegrationServercanactaseitheraserveroraclientinaguaranteed deliverytransaction,theguaranteeddeliverycapabilitiesoftheserverhandleboth inboundtransactionsandoutboundtransactions.Whenaclientinvokesaserviceona server,theserverisactingasaserver.Ifaserviceusesguaranteeddeliverytoinvokea serviceonanotherIntegrationServer,theserverthatinvokestheserviceistheclient.
Inbound transactions from a client application webMethods Integration Server Service A webMethods Integration Server Service B
Client Application Acts as a client
Outbound transactions to another server
For inbound transactions, acts as a server; for outbound transactions, acts as a client
Acts as a server
Theguaranteeddeliverycapabilitiesallowyoutobuildrobust,transactionbasedclient applicationswithouthavingtoembedcomplexerrorhandlingcodetorespondto transientfailures. Important! Usetheguaranteeddeliverycapabilitieswithstateless(i.e.,atomic) transactionsbecausestateinformationcannotbemaintainedfromonerequesttothe next.Asaresult,guaranteeddeliverycapabilitiescannotbeusedwithmultirequest conversationalservices.
324
Configuring the Server for Guaranteed Delivery

ThissectiondescribesconfigurationsettingsthattheIntegrationServerusesfor guaranteeddeliverytransactions.Mostofthesettingshavedefaults.Ingeneral,youwill wanttousethedefaults;however,youcanspecifyalternatesettingsintheserver.cnf serverconfigurationfile.YoucanchangethesesettingbyusingtheSettings > Extended screenoftheIntegrationServerAdministratorasdescribedonpageSwitchingfromthe EmbeddedDatabasetoanExternalRDBMSonpage 79. ForGuaranteedDeliverytowork,theISInternalfunctionalalias(specifiedonthe Settings>JDBC Poolsscreen)mustbeconfiguredtopointtoeithertheembeddedIS InternaldatabaseortoanexternalRDBMS.ForinformationaboutconnectingIntegration Servertodatabasecomponents,seethewebMethodsInstallationGuide. Forinformationaboutusingguaranteeddeliverywithserverclustering,refertothe webMethodsIntegrationServerClusteringGuide. Therearesettingsforbothinboundandoutboundguaranteeddeliverytransactions.
Settings Shared by Both Inbound and Outbound Transactions

watt.server.txMail Usethewatt.server.txMailsettingtospecifytheemailaddressofanadministratorto notifywhenguaranteeddeliverycapabilitiesaredisabledduetoerror(forexample,ifthe serverencountersadiskfullcondition).Anexampleofusingthissettingis
watt.server.txMail=ISAdmin@YourCompany.com.
Thereisnodefaultforthissetting. watt.server.smtpServer Usethewatt.server.smtpServersettingtospecifythedomainname(e.g., purple.webmethods.com)orIPaddress(e.g.132.906.19.22)oftheSMTPserveryouwant theIntegrationServertousewhensendinganemailmessageaboutanerrorduring guaranteeddelivery.Anexampleofusingthissettingis

watt.server.smtpServer=132.906.19.22
Thereisnodefaultforthissetting. Whenanadministratorreceivesanemailnotificationofanerror,theadministrator shouldcorrecttheproblem,thenusetheIntegrationServerAdministratortoreinitialize guaranteeddeliverycapabilities.Forinstructionsonhowtoreinitializeguaranteed delivery,refertoReinitializingGuaranteedDeliveryonpage 329.
Settings for Inbound Transactions

Forinboundtransactions,theservermaintainsajobstoreoftransactionsandthestatusof each.Periodically,theserversweepsthejobstoretoremoveexpiredtransactions;thatis, toremovetransactionsthathaveanelapsedtimetolive(TTL)period.Forinbound requests,theclientmustspecifytheTTLforatransaction.
325
Inadditiontothejobstore,theservermaintainsanaudittraillogofalloperationsit performsforinboundtransactions. Thefollowingdescribestheinboundtransactionsettingsyoucanconfigure. You can configure: Howoftentheserversweepsthejobstoreto removeexpiredtransactions Howtheserverupdatesthestatusof PENDINGtransactionswhenaheuristic failureoccurs Wheretheservermaintainstheaudittraillog forinboundtransactions(ontheserver) Using this setting
watt.server.tx.sweepTime
watt.server.tx.heuristicFailRetry
watt.server.tx.logfile
watt.server.tx.sweepTime Usethe watt.server.tx.sweepTime settingtospecifythenumberofsecondsbetween sweeps(cleanup)ofthejobstoreofinboundtransactions.Theserversweepsthejobstore toremoveexpiredtransactions. Thedefaultis: 60 seconds watt.server.tx.heuristicFailRetry Usethewatt.server.tx.heuristicFailRetrysettingtoindicatewhethertheserveristo reexecuteservicesfortransactionsinthejobstorethatarePENDINGwhentheserveris restartedafterafailure.IfatransactionisPENDING,theservicebeganbutdidnot completeexecutionwhentheserverfailed. Becausetheservercannotdeterminetheexactstatusofaservicerequest,theserver considerstheguaranteedtransactiontohaveencounteredaheuristicfailure.Youcan configuretheservertorespondtoheuristicfailuresasappropriate.Thedefault watt.tx.heuristicFailRetry settingcausestheservertoexecuteaserviceatleastone timeattheriskofreexecutingitasubsequenttimeafteraheuristicfailure.Alternatively, youcanreconfigurethesettingtoguaranteethataserviceisexecutedatmostonetimeat theriskofnotexecutingaserviceduetoaheuristicfailure. Ifthewatt.tx.heuristicFailRetry settingistrue,theserverresetsthetransactionstatus fromPENDINGtoNEW,andtheserverwillretrytheservice.Whenthesettingistrue,a requesttoexecuteaservicecanonlyfailifthetransactionexpiresbeforetheserver executestheservice.(Theclientspecifiesthesettingsthatindicatewhenatransaction expires.) Ifthewatt.tx.heuristicFailRetrysettingisfalse,theserverresetsthetransactionstatus fromPENDINGtoFAILtoindicatetheheuristicfailure;theserverdoesnotretrythe service.Whenthesettingisfalse,arequesttoexecuteaservicecanfailduetoaheuristic failureorduetothetransactionexpiring. Thedefaultis:true
326
watt.server.tx.logfile Usethewatt.server.tx.logfilesettingtospecifythefile(ontheserver)inwhichthe servermaintainsanaudittraillogofalloperationsitprocessesforinboundguaranteed deliverytransactions. Thedefaultis:logs\txinyyyymmdd.log watt.debug.logfile Usethewatt.debug.logfile settingtospecifythefileinwhichtheservermaintainsan audittraillogofalloperationsitprocessesforinboundguaranteeddeliverytransactions. Thedefaultis:logs/server.log
Settings for Outbound Transactions

Youcandisabletheuseofguaranteeddeliveryforoutboundtransactions.However,if youallowguaranteeddeliveryforoutboundtransactions,theservermaintainsaseparate jobstoreforthetransactions.Similartotheinboundjobstore,theserverkeepsthestatus ofeachtransactionintheoutboundjobstore.Ifaservicerequestfails,theserverwaitsa specifiedamountoftimebeforeresubmittingtherequest.Theserverperiodically processesthejobstoretoidentifytransactionsthatitneedstosubmit. Theservermaintainsathreadpooltoservicependingoutboundrequests.Youcan configurehowmanyclientthreadstheservershouldmaintaininthethreadpool. Theserveralsomaintainsaseparateaudittraillogofalloperationsitperformsfor outboundtransactions. Thefollowingdescribesthesettingsyoucanconfigure. You can configure: Whetheryouwanttodisableguaranteeddeliveryfor outboundtransactions. ThedefaultTTLvalueforoutboundtransactions. Howlongtheservershouldwaitbeforeresubmitting failedrequests. Howoftentheserverprocessesthejobstoreto identifytransactionsthatitneedstosubmit. Howmanyclientthreadstheservershouldmaintain inthethreadpoolthatitusestoservicepending requests. Using this setting
watt.tx.disabled
watt.tx.defaultTTLMins watt.tx.retryBackoff
watt.tx.sweepTime
watt.tx.jobThreads
watt.tx.disabled Usethewatt.tx.disabledsettingtospecifythatyouwanttodisabletheuseof guaranteeddeliveryforoutboundrequests.Bydefault,theserverallowstheuseof guaranteeddeliveryforoutboundtransactions.Thedefaultisfalse.Ifanunexpected exceptionalconditionalisencountered,guaranteeddeliverymaybedisabledbythe server.Inthiscase,thewatt.tx.disabledpropertywillbesettotrue.
327
Thedefaultis:false watt.tx.defaultTTLMins Usethewatt.tx.defaultTTLMinssettingtospecifythedefaulttimetolive(TTL)valuefor outboundguaranteeddeliverytransactions.Specifythenumberofminutesyouwantthe servertomaintainoutboundtransactionsinthejobstorewhenaserviceinitiatingan outboundtransactiondoesnotspecifyaTTLvalue. Thedefaultis:30 watt.tx.retryBackoff Usethe watt.tx.retryBackoffsettingtospecifythenumberofsecondstowaitaftera servicerequestfailurebeforetheJobManagerresubmitstherequesttoexecutethe servicetotheIntegrationServer. Thedefaultis:60 watt.tx.sweepTime Usethe watt.tx.sweepTimesettingtospecifythenumberofsecondsbetweensweepsof thejobstoreofoutboundtransactions.Theserversweepsthejobstoretoidentify transactionsthatitneedstosubmit. Thedefaultis:60 watt.tx.jobThreads Usethe watt.tx.jobThreadssettingtospecifythenumberofclientthreadsyouwantto makeavailableinathreadpooltoservicependingrequests. Thedefaultis:5
Administering Guaranteed Delivery

Whenyouinitializetheserver,itinitializesguaranteeddeliverycapabilities.Youcanuse theIntegrationServerAdministratortoshutdown,reinitialize,andtestguaranteed delivery.
Shutting Down Guaranteed Delivery

Youcanshutdownandreenableguaranteeddeliverycapabilitieswithouthavingtoshut downtheserver. Youmightwanttoshutdownguaranteeddeliverytoperformsomeadministration functions,suchascorrectingconfigurationerrorsorstartinganewaudittraillog.(To startanewaudittraillog,moveorrenametheexistinglog;theserverautomatically startsanewlogifonedoesnotalreadyexist.)
328
To shut down guaranteed delivery 1 2 3 4 5 6 7 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuoftheNavigationpanel,clickManagement. Inthelistofpackages,clickWmRoot. ClickBrowse Services in WmRoot. Inthelistofservices,click wm.server.tx:shutdown. ClickTest shutdown.Theserverdisplaysthetestscreenforthewm.server.tx:shutdown service. ClickTest (without inputs).Theserverdisablestheguaranteeddeliverycapabilitiesfor inboundtransactions.
Reinitializing Guaranteed Delivery

Reinitializeguaranteeddeliveryifitbecomesdisabled.Thissectiondescribesthe procedurestoreinitializeguaranteeddeliveryforinboundtransactionsandoutbound transactions.
Inbound Transactions
Ifyoushutdowntheguaranteeddeliverycapabilitiestocorrectaconfigurationproblem ortomakeanadministrativechange,youcanreinitializeguaranteeddeliveryusingthe IntegrationServerAdministrator. Youcanalsousethisproceduretoreinitializeguaranteeddeliveryifitbecomesdisabled duetoanerror(forexample,becauseofadiskfullconditionoriftheservercouldnot locatethejobstore).Reinitializeguaranteeddeliveryafteryoucorrecttheproblem. To reinitialize guaranteed delivery for inbound transactions 1 2 3 4 5 6 7 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuoftheNavigationpanel,clickManagement. Inthelistofpackages,clickWmRoot. ClickBrowse Services in WmRoot. Inthelistofservices,click wm.server.tx:init. ClickTest init.Theserverdisplaysthetestscreenforthewm.server.tx:initservice. Click Test (without inputs).Theserverreinitializestheguaranteeddeliverycapabilities forinboundtransactions.
329
Outbound Transactions
Ifguaranteeddeliverycapabilitiesforoutboundtransactionsbecomedisabledduetoan error(forexample,becauseofadiskfullconditionoriftheservercouldnotlocatethejob store),usethisproceduretoreinitializeguaranteeddeliveryafteryoucorrectthe problem. To reinitialize guaranteed delivery for outbound transactions 1 2 3 4 5 6 7 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuoftheNavigationpanel,clickManagement. Inthelistofpackages,clickWmRoot. Click Browse Services in WmRoot. Inthelistofservices,click wm.server.tx:resetOutbound. ClickTest resetOutbound.Theserverdisplaysthetestscreenforthe wm.server.tx:resetOutboundservice. ClickTest (without inputs).Theserverreinitializestheguaranteeddeliverycapabilities foroutboundtransactions.
Specifying an E-Mail Address and SMTP Server for Error Messages

Whenyouconfigureguaranteeddelivery,youmustspecifytheemailaddresstowhich theIntegrationServercanissueanerrormessageifguaranteeddeliverybecomes disabled.Inaddition,youmustspecifythedomainnameorIPaddressoftheSMTP serveryouwanttohandletheseemailmessages. To set the e-mail address and SMTP server using the Integration Server Administrator 1 2 3 4 5 6 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickLogging. ClickEdit Logging Settings. Typetheemailaddressfortheadministratortowhomyouwanttheservertosend errornotificationintheService EmailfieldintheEmail Notification sectionofthescreen. Typethedomainname(e.g.,purple.webmethods.com)orIPaddress(e.g. 132.906.19.22)oftheSMTPserveryouwanttheIntegrationServertouse. ClickSave Changes.
330
21
Managing Services
332 332 334 336 337 338 339
About Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Fully-Qualified Service Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Finding Information about Services and Folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running Services When Packages Are Loaded, Unloaded, or Replicated . . . . . . . . . . . . . . . . . Running Services in Response to Specific Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Scheduling Services to Execute at Specified Times . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
331
21 Managing Services
About Services
Aserviceisaserverresidentunitoffunctionalitythatclientscaninvoke.Aservicemight beanentireapplicationorusedaspartofalargerapplication.Thereareseveraltypesof services:flowservices(includingWebserviceconnectors),adapterservices,Java services,andC/C++services. YoucancreateallflowservicesusingthewebMethodsDeveloper.Youcancreate databaseflowservicesfromtheIntegrationServerAdministratoraswell.Youcanalso usetheDevelopertocreateadapterservices,Javaservices,oruseyourowndevelopment environmenttocreateJavaandC/C++services.Formoreinformationaboutthetypesof servicesandhowtocreatethem,refertothewebMethodsDeveloperUsersGuide. Youcandesignateoneormoreservicesinapackageasastartup,shutdown,or replicationservice.Astartupserviceisaservicethattheserverautomaticallyexecutes whenapackageisloaded.Ashutdownserviceisaservicethattheserverautomatically executeswhenapackageisunloaded.Areplicationserviceisaservicethattheserver automaticallyexecuteswhenapackageisreplicated. Toimprovetheperformanceofservices,youcanhavetheservercachetheserviceresults. Then,whentheserverreceivessubsequentrequestsfortheservice,itreturnsthecached resultsratherthanexecutingtheservice.Formoreinformation,seeChapter 19,Caching ServiceResults.
Fully-Qualified Service Names

Thefullyqualifiedservicenameiscomprisedoftwoparts:afolderidentifierandthe servicename.Thefolderidentifierconsistsofoneormorefoldernames.Theservicename isasinglenameoftheservice. Useafoldertogrouprelatedservicestogether.Whenafoldercontainsotherfolders,the nestedfoldersarecalledsubfolders.Forexample,ifyouhaveseveralservicesthat involvefinancialinformation,youmightcreateafoldernamedFinancetoholdthe services.Withinthefinancialservices,theremightbeservicesthatareforpersonal finances.YoumightcreateasubfoldernamedPersonaltoholdthoseservices. Useanynamefortheservicename.Forexample,ifoneofthefinancialservicesobtains stockquotes,youmightnametheservice,StockQuote. Tospecifyafullyqualifiedservicename,identifythefolderportion,thenacolon(:),then theservicename: folder:service Forexample,iftheStockQuoteserviceisintheFinancefolder,thefullyqualified servicenameis: Finance:StockQuote Ifthefolderportionidentifiesmorethanonefolder,separateeachfoldernamewitha period.
332
folder.subfolder1.subfolder2:service Forexample,iftheHomeLoanserviceisinthePersonalfolder,whichiscontainedin theFinancefolder,thefullyqualifiedservicenameis: Finance.Personal:HomeLoan Thefullyqualifiednameofeachservicemustbeuniquewithintheserver.Inaddition,thefully qualifiednameofaservicecannotbethesameasthefullyqualifiednameofany specificationordocumenttypethatresidesontheserver. Note: The watt.server.illegalNSCharssettingintheserver.cnffile(whichislocated intheIntegrationServer_directory\configdirectory)definesthecharactersthatyou cannotusewhennamingfoldersandservices.Tovieworchangethissetting,usethe Settings>ExtendedscreenfromtheIntegrationServerAdministratorasdescribedon pageSwitchingfromtheEmbeddedDatabasetoanExternalRDBMSonpage 79.
Package Names and Service Names

Therelationshipbetweenthepackagenameandthefoldernamecancauseconfusion. Thenameofthepackagetowhichaservicebelongshasnobearingonthenamesofthe servicesandfoldersitcontains.Nordoesitaffecthowitisreferencedbyaclient application.Forexample,ifyoumoveaservicecalledPersonnel:GetDeptNamesfroma packagecalledAdmintoapackagecalledEmployeeDatayouwillnotaffectclient applicationsthatreferencethatservice;itwillstillbereferencedbythename Personnel:GetDepNames. Becausethefullyqualifiednameofeachservicemustbeuniquewithintheserver,you cannothavetwoidenticallynamedservicesintwodifferentpackagesonthesameserver.
333
Finding Information about Services and Folders

Thissectiondescribeshowtolisttheservices(andfolders)onyourserveranddisplay informationaboutaspecificservice.
Listing Folders and Services

TheFolders and ServicesscreensoftheIntegrationServerAdministratorlisttheservices thatresideonyourserverandthefolderswithwhichtheyareassociated. To list folders and services 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. FromthePackagesmenuintheNavigationpanel,clickManagement. ClickBrowse Folders. Toviewthecontentsofafolder,clickthefoldername.Theserverdisplaysanother Folder Listscreen.Fortheselectedfolder,theserverdisplaysthesubfoldersfollowed bytheservices. Youcancontinuetoclickonfoldernamestoviewsubfoldersandservicesinselected folders. Note: TheserverwillonlydisplayfoldersandelementstowhichyouhaveList access.
Displaying Information about a Service

ThePackages > Management > WmPublic > Services > service screendisplaysavarietyof informationaboutaselectedserviceorspecification. To display information about a service 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. FromthePackagesmenuintheNavigationpanel,clickManagement. FromthePackage List,clickthepackagewhoseservicesyouwanttoview. ClickBrowse Services in packagename.
334
Clickthenameoftheserviceorspecificationforwhichyouwanttodisplay information. Theserverdisplaysascreenthatcontainsthefollowingsections: Section General Info Description Identifies Thefolderinwhichtheserviceiscontainedandtheservice name. Thenameofthepackagewithwhichtheserviceis associated. Thetypeofservice:Flow,Java,orC/C++. Whetherornottheserviceisstateless. Universal Name Thenamethatwillbeusedtoqualifythenameofthisservice. Itconsistsofthenamespacenameandthelocalname. Byconvention,aURIisgenerallyusedasthenamespacename (e.g.,http://www.gsx.com/gl).Thisassuresthattheuniversal nameisgloballyunique. Thelocalnameuniquelyidentifiestheservicewithinthe collectionencompassedbynamespacename.Mostsitesuse theunqualifiedportionoftheservicenameasthelocalname Youmayuseanysequenceofcharactersordigitsforthe namespacenameandthelocalname. Java-Specific Parameters Access Control ForaJavaservice,identifiestheJavaclassnameandmethod namefortheservice. IdentifiestheACLsassignedtotheserviceorspecification.For informationaboutACLs,services,andspecifications,see Chapter ,ControllingAccesstoResourceswithACLs. Identifieswhethertheserveristosavetheresultsofexecuting thisserviceincache.Forinformation,seeChapter 19,Caching ServiceResults. Identifiesthenameofabindingservicethatparsesincoming XMLfortheservice,theoutputtemplateassociatedwiththe service(ifany),andthetypeoftheoutputtemplate(HTMLor XML).Forinformationaboutoutputtemplates,refertothe DynamicServerPagesandOutputTemplatesDevelopersGuide.
Cache Control
Data Formatting
335
Working with Services

Youcanperformthefollowingtasksthatactonservices.
Manually Adding a Service to the Server

IfyouhaveJavaorC/C++servicesthatwerenotcreatedusingtheDeveloper,youmust manuallyaddthemtotheserverusingthejcodeutility.SeeBuildingJavaServiceswith YourOwnIDEinthewebMethodsDeveloperUsersGuideformoreinformation.
Testing Services
Youcantesttheoperationofaservice.Thisallowsyoutoquicklyandeasilyverifythe operationofaserviceandtestitwithspecialcaseinputvalues. Note: TheDeveloperoffersamorerobustenvironmentfortestingservices.
To test a service 1 2 3 4 5 6 7 OpentheIntegrationServerAdministratorifitisnotalreadyopen. FromthePackagesmenuintheNavigationpanel,clickManagement. FromthePackage List,clickthepackagewhoseserviceyouwanttotest. ClickBrowse Services in packagename. Clickonthenameoftheserviceyouwanttotest. Totesttheservice,clickTest servicename. TheserverdisplaystheTest ServiceNamescreen. Ifyouwanttotesttheservicewithinputvalues,fillintherequiredinputinformation intheAssign Input ValuessectionofthescreenandclickTest with inputs. Ifyouwanttotesttheservicewithoutspecifyinginputvalues,clickTest (without inputs).
336
Running Services When Packages Are Loaded, Unloaded, or Replicated

Tohavetheserverautomaticallyexecuteaprescribedsetofoperationseachtimethe serverloadsorunloadsapackagefrommemoryorreplicatesapackage,youcanidentify startup,shutdown,andreplicationservices.Thissectionprovidesanoverviewofstartup, shutdown,andreplicationservices. ToidentifytheseservicesyoumustusetheDeveloper.SeethewebMethodsDeveloper UsersGuideforinstructions.
What Is a Startup Service?

Astartupserviceisonethattheserverautomaticallyexecuteswhenitloadsapackage. Theserverloadsapackage: Atserverinitialization(ifthepackageisenabled) WhensomeoneusestheIntegrationServerAdministratortoreloadapackage WhensomeoneusestheIntegrationServerAdministratortoenableapackage Startupservicesareusefulforgeneratinginitializationfilesorassessingandpreparing (e.g.,settinguporcleaningup)theenvironmentbeforetheserverloadsapackage. However,youcanuseastartupserviceforanypurpose.Forexample,youmightwantto executeatimeconsumingserviceatstartupsothatitscachedresultisimmediately availabletoclientapplications.
What Is a Shutdown Service?

Ashutdownserviceisonethattheserverautomaticallyexecuteswhenitunloadsa packagefrommemory.Ifapackageisinmemory,theserverunloadsthepackage: Atservershutdownorrestart WhensomeoneusestheIntegrationServerAdministratortodisablethepackage Beforetheserverremovesthepackagefrommemorywhensomeoneusesthe IntegrationServerAdministratortoreloadapackage Shutdownservicesareusefulforexecutingcleanuptaskssuchasclosingfilesand purgingtemporarydata.Youcouldalsousethemtocaptureworkinprogressorstate informationbeforeapackageunloads.
337
What Is a Replication Service?

Areplicationserviceisonethattheserverautomaticallyexecuteswhenitpreparesto releaseorarchiveapackage.Theserviceexecuteswhentheadministratorclicksthe Create Release linkonthePackages > Publishing > Create and Delete Releases screenorthe Archiveicon onthePackages > Management screen. Replicationservicesprovideawayforapackagetopersiststateorconfiguration informationsothatthisisavailablewhenthepackageisactivatedontheremoteserver.
Guidelines for Using Startup, Shutdown, and Replication Services

Keepthefollowingguidelinesinmindwhenusingstartup,shutdown,andreplication services. Whenyoucreateastartuporshutdownservice,youmustregisterthatserviceinthe packagewithwhichitwillbeused.Whenyoucreateareplicationservice,youcan registeranyvalidservicefromanyloadedpackageontheserver,includingthe currentpackageitself. Becauseservicesinapackagearenotmadeavailabletoclientsuntilthatpackages startupservicesfinishexecuting,youshouldavoidimplementingstartupservices thataccessbusyremoteservers.Theywilldelaytheavailabilityofotherservicesin thatpackage. Youmayassignoneormorestartupservicestoapackage;however,youcannot specifytheorderinwhichtheywillexecute.Ifyouhaveaseriesofoperationsthat mustexecuteinaspecificorder,encodetheentiresequencewithinasingleserviceor haveastartupserviceinvokeothers. SeethewebMethodsDeveloperUsersGuideforinstructions.
Running Services in Response to Specific Events

TheEventManagerrunsontheserver,monitoringitforevents.Aneventisaspecific actionthattheEventManagerrecognizesandaneventhandlercanreactto.Anevent handlerisaserviceadeveloperwritestoperformanactionwhenaspecificeventoccurs. TheEventManagerrecognizesanumberofdifferentevents.Forexample,analarmevent occurswhenthewebMethodsIntegrationServerthrowsanexceptionregardingthe statusorhealthoftheserver.Theservergeneratesalarmeventswhenausercannotlog ontotheserver,aportcannotbestarted,auserisdeniedaccesstoaport,andsoon. DeveloperscontroltheEventManagerthroughtheDeveloper.Theserversaves informationforeventtypesandeventsubscriptionsintheeventcfg.binfile.Thisfileis generatedthefirsttimeyoustartanIntegrationServerandislocatedinthefollowing directory:IntegrationServer_directory\config.Thereisnoneedforyoutoworkwiththis filedirectly;however,ifyouareclusteringIntegrationServers,youneedtocopythisfile fromoneservertoanothertoduplicateeventsubscriptionsonallserversinthecluster.
338
FormoreinformationaboutusingtheEventManager,refertothewebMethodsDeveloper UsersGuide.
Scheduling Services to Execute at Specified Times

Usetheserversschedulingfunctiontoscheduleservicestoexecuteattimesyouspecify. Servicesthatyouschedulearereferredtoasusertasks. Youcanviewalistofandupdatetheschedulingoptionsforscheduledusertasks.You canalsocancelascheduledusertaskbeforetheservercompletesallscheduled executionsortemporarilysuspendthetasksexecution.Aftertheservercompletesall scheduledexecutionsofaservice,itmarksthetaskExpired. Theserverprovidesusertasksthatyoucanmodify.Forexample,theserversuppliesthe wm.server.dispatcher:deleteExpiredUUIDserviceifyouconfiguredadocumenthistorydatabase forexactlyonceprocessing.Thisserviceremovesexpiredentriesfromthedocument historydatabase.Eventhoughtheserverscheduledthistask,youcanmodifyhowoften theserviceruns. Inadditiontothescheduledusertasksthatyousetup,theserverschedulessystemtasks thatitperformsfornormalsystemoperation.Youcanview,butnotupdateorcancel,the scheduledsystemtasks. Note: Youcanalsoperformschedulingbyusingasetofbuiltinservices.Seethe webMethodsIntegrationServerBuiltInServicesReferenceformoreinformation.
Scheduling a User Task

Toscheduleausertask,youspecify: Fully-qualified service name. Toindicatetheservicethatyouwanttheservertoexecute, youspecifythefullyqualifiednameoftheservice.Forinformationaboutspecifying servicenames,seeFullyQualifiedServiceNamesonpage 332. User name that you want the server to use when running the service. Theserverrunsthe serviceasiftheuseryouspecifyistheauthenticateduserthatinvokedtheservice.If theserviceisgovernedbyanACL,besuretospecifyauserthatisallowedtoinvoke theservice. When and how often you want the service to run.Aservicecanrunonceorrepeatedly. Run Once. Theserverexecutestheserviceasingletime. Repeating.Theserverexecutestheservicerepeatedlyatanintervalyouspecify,such asevery5minutes. Complex Repeating. Theserverexecutestheservicerepeatedlyattimesyouspecify, suchaseverydayat10a.m.
339
Whether or not you want the scheduled user task to run on other Integration Servers in the cluster.Selectthisoptionifyouhavesetupclusteringandwantthetasktorunonany orallIntegrationServersinyourclusterofIntegrationServers. $anyspecifiesthatataskcanrunonanyserverinthecluster. $allspecifiesthatataskistorunonallserversinthecluster. <specific_server> specifiesthatthetaskistorunonaserveryouchoose. Action to take if a task is overdue. Iftheserverdetectsthatataskhasmisseditsscheduled executiontime,theserverwilleitherstartthetaskimmediately,skipthisexecutionof thetask,orsuspendthetaskandwaitforadministratoraction.
Using the Once Option

WhenyouscheduleausertaskusingtheOnceoption,theserverexecutestheserviceone timeonthedateandatthetimethatyouspecify.Aftertheserverexecutestheserviceat thescheduledtime,theservermarksthetaskExpired.
Using the Simple Repeating Option

Whenyouusethesimplerepeatingoption,theservicerepeatsbasedonatimeinterval youspecify. Setting Start Date Indicates Thedateonwhichyouwanttheservertoexecutetheserviceforthefirst time.UsetheformatYYYY/MM/DDtospecifythedate.Ifyouleavethis fieldblank,theserverstartsthetaskonthecurrentday Thetimeatwhichyouwanttheservertobeginexecutingtheservice. UsetheformatHH:MM:SStospecifythetime(usinga24hourclock).If youleavethisfieldblank,theserverstartsthetaskimmediately. Thedateonwhichyouwanttheservertoexecutetheserviceforthelast time.UsetheformatYYYY/MM/DDtospecifythedate.Ifyouleavethis fieldblank,theserverexecutestheserviceforanindefiniteperiodof timeoruntilyoucancelthescheduledusertask. Thetimeonthelastdateatwhichyouwanttheservertoexecutethe service.UsetheformatHH:MM:SStospecifythetime(usinga24hour clock).Ifyouleavethisfieldblank,theserverusesthecurrenttime. Whethertheservershouldwaitforthecurrentexecutionofaserviceto completebeforestartingthenextone. Timeinterval,inseconds,atwhichyouwanttheservicetoexecute.For example,ifyouwanttheservertoexecutetheserviceevery24hours, specify86400secondsfortheinterval.
Start Time
End Date
End Time
Repeating/ Repeat after Completion Interval
340
ThefollowingshowsexamplesofhowtousetheSimpleRepeatingoptionsettings: If you want the service to execute EveryhouronJuly1stintheyear 2007. For this setting: StartDate StartTime EndDate EndTime Interval Specify 2007/07/01 00:00:00 2007/07/01 00:00:00 60
Using the Complex Repeating Option

WiththeComplex Repeatingoption,theservicerepeatsbasedondatesandtimesyou specify.Thisoptionoffersthegreatestflexibilityforspecifyingwhenyouwanttheserver toexecutetheservice. Specifyanycombinationofthefollowingsettingstoindicatewhenandhowoftenyou wanttheservertoexecutetheservice: Setting Start Date Indicates Thedateonwhichyouwanttheservertoexecutetheserviceforthefirst time.UsetheformatYYYY/MM/DDtospecifythedate.Ifyouleavethis fieldblank,theserverexecutesthetaskatthefirstdatespecifiedbythe remainingsettings. Thetimeatwhichyouwanttheservertobeginexecutingtheservice. UsetheformatHH:MM:SStospecifythetime(usinga24hourclock).If youleavethisfieldblank,theserverusesthecurrenttime. Thedateonwhichyouwanttheservertoexecutetheserviceforthelast time.UsetheformatYYYY/MM/DDtospecifythedate.Ifyouleavethis fieldblank,theserverexecutestheserviceforanindefiniteperiodof timeoruntilyoucancelthescheduledusertask. Thetimeonthelastdateatwhichyouwanttheservertoexecutethe service.UsetheformatHH:MM:SStospecifythetime(usinga24hour clock).Ifyouleavethisfieldblank,theserverusesthecurrenttime. Whethertheservershouldwaitforthecurrentexecutionofaserviceto completebeforestartingthenextone.
Start Time
End Date
End Time
Repeating/ Repeat after Completion Months Days
Themonths(JanuarythroughDecember)thatyouwanttheserverto executetheservice. Thedaysofthemonths(0through31)thatyouwanttheserverto executetheservice.
341
Setting Weekly Days Hours Minutes
Indicates Thedaysoftheweek(SundaythroughSaturday)thatyouwantthe servertoexecutetheservice. Thehoursofthedaysthatyouwanttheservertoexecutetheservice. Theminuteofthehourthatyouwanttheservertoexecutetheservice.
Theservercombinesallyourselectionstodeterminewhentoexecutetheservice.Ifyou donotselectaniteminoneoftheabovesettings,theserverassumesallitemsforthe selection.Forexample,ifyoudonotspecifyamonth,theserverassumesyouwantthe servicetoexecuteeverymonth.Ifyoudonotselectanyitemsforanyofthesettings,the serverassumesyouwanttheservicetoexecuteeverymonth,everyday,allweekdays, everyhour,andeveryminute;inotherwords,theserverexecutestheserviceevery minutefromthetimeyouaddthetask. ThefollowingshowsexamplesofhowtousetheComplexoptionsettings: If you want the service to execute The28thdayofeverymonthat midnightfortheyear2007. For this setting: StartDate StartTime EndDate EndTime Months MonthDays WeekDays Hours Minutes EveryMondayinthemonthsof January,February,andMarchat2:30 p.m.foranindefiniteperiodoftime. StartDate StartTime EndDate EndTime Months MonthDays WeekDays Hours Minutes Specify 2007/01/01 00:00:00 2007/12/31 00:00:00 noselection 28 noselection 0 0 leaveblank leaveblank leaveblank leaveblank January,February,March noselection Monday 14 30
342
If you want the service to execute EveryhourofeveryTuesdayofthe monthofJune,2007.
For this setting: StartDate StartTime EndDate EndTime Months MonthDays WeekDays Hours Minutes
Specify 2007/06/01 00:00:00(orleaveblank) 2007/06/30 00:00:00(orleaveblank) June noselection Tuesday noselection 0 2007/06/01 00:00:00(orleaveblank) 2007/06/30 00:00:00(orleaveblank) June noselection Tuesday noselection noselection
Everyminuteofeveryhourofevery TuesdayofthemonthofJune,2007.
StartDate StartTime EndDate EndTime Months MonthDays WeekDays Hours Minutes
343
Using the Clustering Target Node Options

Ifyouarerunningaclusterofservers,youcancontrolonwhichserverataskruns.You canspecifythatataskrunonthecurrentserver,anotherspecificserver,anyserverinthe cluster,orallserversinthecluster: Setting <specific_server> $any Indicates Thetaskrunsonlyontheserveryouspecify. Thetaskrunsonanyserverinthecluster.Usethisoptionifthetask onlyneedstorunononeserveranditdoesntmatterwhichone.For example,ifallserversintheclustershareasingledatabasefora partsinventoryapplication,andaparticularfunctionneedstorun onthatdatabaseonceaday,anyserverintheclustercanperform thatfunction.The$anyoptionisthedefaultsettingwhenclustering isenabled. Note: The$any optiondoesnotspecifyanorderinwhichserversare usedtoexecutetasks.Inotherwords,noloadbalancingis performed.Instead,aninstanceoftheschedulerrunsoneachserver inthecluster.Periodically,eachinstancechecksthedatabasein whichinformationaboutscheduledjobsisstored.Thefirst schedulerinstancetofindataskthatisduetostartrunsit,then marksthetaskascompleteinthedatabase.Theschedulerinstances runningontheotherserversintheclusterthenknownottorunthe task.Thisbehaviorwillnotchangeifyouinstallathirdpartyload balancer.
344
Setting $all
Indicates Ifyouselect$all,thetaskrunsonallserversinthecluster.For example,supposeyourunanapplicationoneachserverinthe cluster,andeachservermaintainsitsowndatabaseforthat application.Ifyouneedtorunacleanuptaskagainstallthe databaseseveryday,thenfromoneserveryoucanscheduleataskto runeverydayonalltheserversinthecluster. Whenyouscheduleatasktorunonallserversinthecluster,the serverdividesthetaskintoamainorparenttask,andachildtaskfor eachserverinthecluster.Youcanperformsomeactions(activate, suspend,delete)individuallyonthechildtasks,butifyouwantto changethecharacteristicsofatask,youmustdosothroughthe parenttask. Youmightseedifferentstatusesamongtheparentandchildtasks. Forexample,youmighthaveasituationwheretheparentstatusis Active,onechildstatusisActive,andtheotherchildstatusis Suspended.Ingeneral,thestatusoftheparenttaskwillbeActiveif atleastonechildtaskisactiveorrunning,Suspendedifallchild tasksaresuspended,orExpired,ifallchildtasksareexpired. Thefollowingpictureshowshowparentandchildtasksare displayedontheServer > Schedulerscreen.
Tasks in a Clustered Environment
If you schedule a task to run on all servers in the cluster, the server divides the task into Parent and Child tasks.
If you schedule a task to run on any server in the cluster, the server shows the target server as Any cluster node.
EastCoastd5500:7100
Parent Task Child Tasks
EastCoastd5500:7100
WestCoastd5500:7100
In a Child task, you cannot link to the service.
In the Parent task, the target server is shown as All cluster nodes.
If you suspend, resume, or cancel a parent task, the server suspends, resumes, or cancels the associated child tasks as well.
345
To schedule the execution of a service 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheServermenuoftheNavigationpanel,clickScheduler. ClickCreate a scheduled task. SettheService Informationparametersasfollows: For this parameter Description folder.subfolder:service Run As User Specify Adescriptionofthetask. Thefullyqualifiedservicenameoftheserviceyouwant theservertoexecute. Theusernameyouwanttheservertousewhenrunning theservice.Click tosearchforandselectyouruser.A usercanbeselectedfromthelocalorcentraldirectory. Cluster Target Node Whetheryouwantthetasktorunonotherserversinthe cluster: Select$anyifthetaskneedstorunononlyoneserver inthecluster,anditdoesnotmatterwhichone. Select$allifthetaskneedstorunonallserversinthe cluster. Selectthenamefromthelistofserversintheclusterif thetaskneedstorunononlyaspecificserver. Thedefaultisthecurrentserver. TheCluster Target Nodeoptionisnotavailableifyour serverisnotpartofacluster.Formoreinformationabout runningyourserveraspartofacluster,seewebMethods IntegrationServerClusteringGuide. FormoreinformationabouttheCluster Target Node options,seeUsingtheClusteringTargetNodeOptions onpage 344. 5 SelectanactiontoperformIf the Task Is Overdue. Theserverperiodicallychecksthestatusofscheduledtasks.Ifitfindsataskthat shouldhavestartedbuthasnot,theserverrunsthetaskimmediately,unlessyou havespecifiedaspecialactiontotakeforlatetasks.Theserverperformsthislate actionifthetaskhasmisseditsscheduledstarttimebyanumberofminutesyou
346
specify.Fortasksthatarelatebutdonotexceedthespecifiedperiod,theserverruns thetaskimmediately:
l
Specify Run the task immediately Skip and run at next scheduled time. Suspend
To Runthetaskimmediately,nomatterhowlatethetaskis. Skipthisexecutionofthetask,andrunitagainatthenext scheduledruntime.Thisoptionisnotavailablefortasks thatrunjustonce. Placethetaskinasuspendedstateuntilanadministrator resumesorcancelsthetask.
Note: Theseoptionsdonotapplyforascheduledtaskthathasnotstartedbecause itiswaitingforthecurrentexecutionofthetasktocomplete,ashappenswhenthe Repeat After Completionoptionisselected. 6 SelectRun Once,Repeating,orComplex Repeating toindicatewhenandhowoftenyou wanttheservertoexecutetheservice. If you select Run Once Specify Thedateonwhichyouwanttheservertoexecutethe service. IntheDatefield,enterthedateusingtheformat YYYY/MM/DD.Forexample,ifyouwanttheserverto executetheserviceonMarch11,2007,specify2007/03/11. Thetimeatwhichyouwanttheservertoexecutethe service. IntheTimefield,enterthetimeusingtheformat HH:MM:SS(usinga24hourclock).Forexample,ifyou wanttheservertoexecutetheserviceat1:00:00a.m., specify1:00:00;ifyouwanttheservertoexecutethe serviceat1:00:00p.m.,specify 13:00:00. Formoreinformationaboutusingthisoption,seeUsingthe OnceOptiononpage 340. Repeating Thedateandtimeofthefirstexecution. EnterabeginningdateandtimeintheStart Date andStart Timefields.ForStart Date,usetheformatYYYY/MM/DD. ForStart Time,usetheformatHH:MM:SS(usinga24hour clock). Forexample,ifyouwanttheserviceexecutionstostarton May3,2007at1:00:00p.m.,specify2007/05/03forStart Date and13:00:00 forStart Time.
347
If you select
Specify Thedateandtimeofthelastexecution. EnteranendingdateandtimeintheEnd DateandEnd Time fields.ForEnd Date,usetheformatYYYY/MM/DD.Forthe End Time,usetheformatHH:MM:SS(usinga24hour clock). Forexample,ifyouwanttheserviceexecutionstostopon June4,2007at2:00:00a.m.,specify2007/06/04forEnd Date and02:00:00forEnd Time.OmittingEnd Dateindicatesthat youwantthisservicetoexecuteforanindefiniteperiodof time.IfyouomitEnd Time,theserverusesthecurrenttime. Executioninterval. IntheIntervalfield,enterthenumberofsecondsthatyou wanttheservertowaitbetweenexecutionsoftheservice. Whethertowaitforthepreviousexecutionofaserviceto completebeforestartingthenext. Ifyouwanttheservertowaitforaservicetocomplete executionbeforeitstartsthenextscheduledexecutionof theservice,checkRepeat after completion. Forexample,supposetheGetDataserviceisscheduledtorun everyminute,butsometimestakeslongerthanthatto complete.Bydefault,theserverwillstartthenextexecution eventhoughthepreviousonehasnotyetcompleted. IfyouchecktheRepeat after completionbox,theserverwill waitfortheservicetocompletebeforerunningthenext executionoftheservice.Executionsthatcouldnotrun whiletheservicewasexecutingaredelayed. Formoreinformationaboutusingthisoption,seeUsingthe SimpleRepeatingOptiononpage 340.
Complex Repeating
Thedateandtimeofthefirstexecution. EnterabeginningdateandtimeintheStart Date andStart Timefields.ForStart Date,usetheformatYYYY/MM/DD. ForStart Time,usetheformatHH:MM:SS(usinga24hour clock). Forexample,ifyouwanttheserviceexecutionstostarton May3,2007at1:00:00p.m.,specify2007/05/03forStart Date and13:00:00 forStart Time.IfyouomittheStart Date,the firstexecutionoccursonthefirstdateasindicatedbythe Run Maskparameters.IfyouomitStart Time,theserveruses thecurrenttime.
348
If you select
Specify Thedateandtimeofthelastexecution. EnteranendingdateandtimeintheEnd DateandEnd Time fields.ForEnd Date,usetheformatYYYY/MM/DD.Forthe End Time,usetheformatHH:MM:SS(usinga24hour clock). Forexample,ifyouwanttheserviceexecutionstostopon June4,2007at2:00:00a.m.,specify2007/06/04forEnd Date and02:00:00forEnd Time.OmittingEnd Dateindicatesthat youwantthisservicetoexecuteforanindefiniteperiodof time.IfyouomitEnd Time,theserverusesthecurrenttime. Whenandhowoftentorepeatthetask. UsetheRun Mask parameterstoindicatewhenyouwant theservertoexecutetheservice.Forexamplesofsetting theseparameters,seeUsingtheComplexRepeating Optiononpage 341. Whethertowaitforthepreviousexecutionofaserviceto completebeforestartingthenext. Ifyouwanttheservertowaitforaservicetocomplete executionbeforeitstartsthenextscheduledexecutionof theservice,checkRepeat after completion. Forexample,supposetheGetDataserviceisscheduledto runevery5minutesonMondays,butsometimestakes longerthanthattocomplete.Bydefault,theserverwill startthenextexecutioneventhoughthepreviousonehas notyetcompleted. IfyouchecktheRepeat after completionbox,theserverwill waitfortheservicetocompletebeforerunningtheservice again.Executionsthatcouldnotrunwhiletheservicewas executingareskipped. Formoreinformationaboutusingthisoption,seeUsing theComplexRepeatingOptiononpage 341.
ClickSave Tasks.
349
Viewing Scheduled User Tasks

Performthefollowingproceduretoviewtheusertasksyouhavescheduled. Ifyourserverrunsaspartofaclusterofservers,alltaskswillbevisiblefromtheServer > Schedulerscreensofallserversinthecluster. To view scheduled user tasks 1 2 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheServermenuoftheNavigationpanel,clickScheduler.
Updating Scheduled User Tasks

Performthefollowingproceduretochangetheschedulingparametersforscheduleduser tasks. To update a scheduled user task 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheServermenuoftheNavigationpanel,clickScheduler. Clicktheservicenamefortheusertaskyouwanttoupdate. Ifyourserverispartofaclusterofserversandyouareupdatingthecharacteristicsof ataskthathasbeenscheduledtorunonallserversinthecluster,youmustmakethe changestotheparenttask.Theparenttaskisshownfirstinthelistofentriesforthis taskandcontainsAll cluster nodesintheTargetfield.Thechangesyoumaketothe parenttaskwillautomaticallybecarriedovertothechildtasks.Forinformation aboutworkingwithtasksinaclusteredenvironment,seeUsingtheClustering TargetNodeOptionsonpage 344. 4 5 Updatetheschedulingoptionsfortheselectedusertask.Forinformationaboutthe optionsyoucanspecify,seeSchedulingaUserTaskonpage 339. ClickUpdate Tasks.
350
Suspending Scheduled User Tasks

Performthefollowingproceduretosuspendallscheduledexecutionsofaservice.When yoususpendausertask,itremainsscheduled,butdoesnotexecuteuntilyouresumeits execution.Ifataskexpireswhilesuspended,theservermarksitExpired. Note: Ifyourserverispartofaclusterandyouaresuspendingataskthathasbeen scheduledtorunonallserversinthecluster,youcansuspendthechildtasks individuallyoryoucansuspendallthetasksatoncebysuspendingtheparenttask. TheparenttaskisshownfirstinthelistofentriesforthistaskandcontainsAll cluster nodesintheTargetfield.Thechildtasksfollowtheparenttaskandeachoneshowsa differenttargetserverintheTargetfield.Forinformationaboutworkingwithtasksin aclusteredenvironment,seeUsingtheClusteringTargetNodeOptionson page 344. To suspend a scheduled user task 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheServermenuoftheNavigationpanel,clickScheduler. LocatethetaskintheServiceslist,andclickthe iconintheStatuscolumnto suspendthetask.Theserverdisplaysascreentoconfirmyouwanttosuspendthe task.ClickOK. Theserverreplacesthe suspended. iconwithSuspendedtoindicatethatthetaskisnow
351
Resuming Suspended Scheduled User Tasks

Performthefollowingproceduretoresumeallscheduledexecutionsofataskthathas beensuspended. Note: Ifyourserverispartofaclusterandyouareresumingataskthathasbeen scheduledtorunonallserversinthecluster,youcanresumethechildtasks individuallyoryoucanresumeallthetasksatoncebyresumingtheparenttask.The parenttaskisshownfirstinthelistofentriesforthistaskandcontainsAll cluster nodes intheTargetfield.Thechildtasksfollowtheparenttaskandeachoneshowsa differenttargetserverintheTargetfield.Forinformationaboutworkingwithtasksin aclusteredenvironment,seeUsingtheClusteringTargetNodeOptionson page 344. To resume execution of a suspended user task 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheServermenuoftheNavigationpanel,clickScheduler. LocatethetaskintheServiceslist,andclickSuspendedintheActivecolumntoactivate thetask.Theserverdisplaysascreentoconfirmyouwanttoresumethetask.Click OK. TheserverreplacesSuspendedwiththeActive availabletoexecuteagain. icontoindicatethatthetaskis
Canceling Scheduled User Tasks

Performthefollowingproceduretocancelausertaskbeforeallscheduledexecutionsof theservicearecomplete. Note: Whenyoucancelascheduledtask,theserverpermanentlyremovesitfromthe databasethatholdsthejobqueue. To cancel a scheduled user task 1 2 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheServermenuoftheNavigationpanel,clickScheduler.
352
Clickthe iconintheRemovecolumnfortheusertaskyouwanttocancel.The serverissuesaprompttoverifythatyouwanttocanceltheusertask.ClickOK. Note: Ifyourserverispartofaclusterandyouarecancelingataskthathasbeen scheduledtorunonallserversinthecluster,youcancancelthechildtasks individuallyoryoucancancelallthetasksatoncebycancelingtheparenttask.The parenttaskisshownfirstinthelistofentriesforthistaskandcontainsAll cluster nodes intheTargetfield.Thechildtasksfollowtheparenttaskandeachoneshowsa differenttargetserverintheTargetfield.Forinformationaboutworkingwithtasksin aclusteredenvironment,seeUsingtheClusteringTargetNodeOptionson page 344.
Viewing the Scheduled System Tasks

Theserverneedstoperformsystemtasksperiodically,suchasexpiringsessions.The serverschedulesthesetasks.Performthefollowingproceduretoviewthescheduled systemtasks. To view the scheduled system tasks 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheServermenuoftheNavigationpanel,clickScheduler. ClickView system tasks. TheserverdisplaystheSystem Tasksscreen.Itliststhenamesofeachscheduledtask, thenextdateandtimetheserveristoexecutethetask,andhowoften(Interval)the serveristoexecutethetask. Note: TheSystem Tasksscreenshowsthetasksforlocalserveronly;ifyouarerunning aclusterofservers,youwillnotseethesystemtasksforotherserversinthecluster.
353
354
22
Locking Administration and Best Practices

356 356 356 359
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Choosing Local Server Locking or VCS Integration Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disabling and Re-enabling Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
355
22 Locking Administration and Best Practices
Introduction
Thischaptercontainsinformationintendedfortheserveradministratoranduserswho regularlyreplicateandpublishpackagesaspartoftheproductionprocess.
Choosing Local Server Locking or VCS Integration Locking

YoucanconfigurethewebMethodsIntegrationServertosupporteitherofthefollowing twoformsoflocking: Locallocking,appliedwithintheIntegrationServerfilesystem. Lockingresultingfromintegrationwithathirdpartyversioncontrolsystem(VCS) repository;inthiscase,elementsarelockedandunlockedasyoucheckthemoutof andintotheVCSrepository. Thelockingadministrationtasksdescribedinthischapterrefertolocallockingonthe IntegrationServer.Ifyourserverenvironmentdoesnotmakeuseofaversioncontrol system,configuretheIntegrationServerforlocallockingasdescribedinthefollowing sections. Ifyouwanttoworkwithathirdpartyversioncontrolsystem,seethewebMethodsVersion ControlSystemIntegrationDevelopersGuideinthewebMethods_directory\_documentation directoryofyourwebMethodsinstallation.Thisguideprovidesinformationabouthow toimplementandadministerfilelockingwiththeVersionControlSystemIntegration feature.
Disabling and Re-enabling Locking

TheremaybetimesinwhichyoudonotwanttoimplementlockingontheIntegration Server.Ifyouareaserveradministrator,youcandisableandreenablelockingbyediting theconfigurationparametersinIntegrationServer_directory\config\server.cnf.
Before You Begin

Makesurethatallusershavecompleteddevelopmentontheserverandunlockedall elements. CloseallDevelopersessions.Afteryouchangetheextendedsettingsinthefollowing procedure,userswillneedtoopenanewDevelopersession.
356
Procedure
Todisableorreenablelocking,youusetheIntegrationServerAdministratoror manuallyeditserver.cnf.ThefollowingproceduredescribestheIntegrationServer Administratorprocedure. Makesurethatyouonlyusethismethodofchangingthesettings.Later,ifyouchangethe settingsbyeditingserver.cnf,conflictscanoccur. To disable locking on the Integration Server 1 2 3 4 CompletethetasksinBeforeYouBegin. IntheIntegrationServerAdministrator,underSettings,clickExtended. ClickEdit Extended Settings. IntheExtendedSettingsbox,typeakeyandvalueaccordingtothefollowingtable. If you want to... Disableuserlockingandshownolocks Disableuserlockingbutshowsystem locks Extended Settings Screen Type this...
watt.server.ns.lockingMode=none watt.server.ns.lockingMode=system
5 6
ClickSave Changes.Theinformationissavedto IntegrationServer_directory\config\server.cnf. RestarttheIntegrationServer.Theupdatedsettingsarenowineffect.
357
To re-enable locking on the Integration Server 1 2 3 4 CompletethetasksinBeforeYouBeginonpage 356. IntheIntegrationServerAdministrator,underSettings,clickExtended. ClickEdit Extended Settings. IntheExtendedSettingsbox,setthevalueofwatt.server.ns.lockingModetofull. Extended Settings Screen
5 6
ClickSave Changes.Theinformationissavedto IntegrationServer_directory\config\server.cnf. RestarttheIntegrationServerforthechangestotakeeffect.
358
Best Practices
Remote Server Configuration
ItisnotrecommendedthatyouuseCooperativeDevelopmentfunctionalityinan IntegrationServercluster.Lockinginformationforelementscouldbeinadvertently sharedwithanotherIntegrationServerinthecluster.UseastandaloneIntegration Servernotacluster,whiledevelopingtoeliminatetheseCooperativeDevelopment problems.
Server User Names

WhenloggingontotheIntegrationServer,useadistinctusername.Lockingisbased onyourusername,soitisimportantthateachuserlogontotheserverwithaunique username(notAdministratororDeveloper).
Package Replication and Publishing

Alwaysbackupyourpackageseverydayornightusingpackagereplicationand publishing.Becauselockinginformationdoesnottravelwithpackages(orpartial packages)whentheyarereplicated,itisrecommendedthatyouapplyaversionto eachpackageaccordingtodate.Donotreplaceoroverwritepackages;deletetheold packageentirelyandtheninstallthenewpackage. Note: Ifyoudoreplaceoroverwritepackages,webMethodsIntegrationServer takestheintersectionofelementsintheNavigationpanel.Itwillalsomovethe existingpackagetothe\replicate\salvagefolder. Whenyoureplicateandpublishapackage,thelockinginformationisnotpreserved. Thisisexpectedbehaviorandispartofthefeaturesdesign.Youcan,however, preservesystemlocks(readonlyfileattributes). Beforeyoupublishapackage,keepinmindthatuserlocksarenotpreserved. Whenyousalvageadeletedpackage,lockinformationisnotpreserved.Beforeyou salvageordeleteapackage,makesurethatalllocksareremovedfromthedestination package. Itisnotrecommendedthatyouusesystemoruserlockingonpackagesthatare frequentlyreplicatedand/orpartiallyreplicated.Forexample,whensending frequentlyupdatedpackagestopartners.
Package and Folder Organization

UseasinglepackageorfolderperdeveloperorperJava/Cservice.
359
Source Code
Iftherehasbeenasignificantchangetothesourcecode,alwaysreloadthepackageto reflectthelatestsystemlocks.
Upgrading webMethods Integration Server

WhenyouupgradethewebMethodsIntegrationServertoanewversion,youloseall lockinformation.Therefore,beforeupgrading,makesurethatalllocksareremoved andallchangesaresaved.
360
23
Managing Broker/Local Triggers

362 363 371 379 380 384
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing Document Retrieval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing Document Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Limiting Server Threads for Broker/Local Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Cluster Synchronization for Trigger Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modifying Broker/Local Trigger Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
361
23 Managing Broker/Local Triggers
Introduction
Inapublishandsubscribesolution,theretrievalandflowofdocumentsthroughthe IntegrationServerconsumesresources,primarilyserverthreadsandmemory.Therateat whichtheIntegrationServercanretrieveandprocessdocumentsisdeterminedbythe availabilityoftheseresources.However,serverresourcesalsoneedtobeavailableto performotherfunctions.TheIntegrationServerAdministratorprovidescontrolsfor managingresourcesconsumedbydocumentretrievalanddocumentprocessing.Youcan usethesecontrolstobalancetheresourcedemandsfordocumentretrievaland processingwiththeserverresourcesneededtoperformotherwork. Specifically,youcanusethecontrolsprovidedbyIntegrationServerAdministratorto: Increaseordecreasethenumberofserverthreadsusedtoretrievedocumentsfrom theBroker. Decreasethecapacityofalltriggerqueues. Suspenddocumentretrievalforoneormoretriggers. Increaseordecreasethenumberofserverthreadsusedtoprocessdocuments. DecreasethenumberofthreadsthattheIntegrationServercanusetoprocess documentsforconcurrenttriggerssimultaneously. Suspenddocumentprocessingforoneormoretriggers. Changetheconfiguredtriggerqueuecapacity,refilllevel,orexecutionthreadsfora specifictrigger. Additionally,theIntegrationServerAdministratorprovidesaclustersynchronization featurethatyoucanusetopropagateselectedchangestootherIntegrationServersina clusterautomatically. Thesecontrolscanbeusefulinaproductionenvironmenttofreeupserverthreadsand memorytoaccommodateanunexpectedserverload(suchasasuddeninfluxofHTTP requests)orinanticipationofahighusagetime.Youcanalsousethecontrolsduringthe capacityplanningstageofyourprojecttodeterminetheconfiguredvaluesfortriggers andserverthreadusage. Thefollowingsectionscontainmoreinformationaboutmanagingdocumentretrieval anddocumentprocessingusingtheprovidedcontrols.
362
Managing Document Retrieval

Withinthepublishandsubscribemodel,documentretrievalistheprocessinwhichthe IntegrationServerusesaserverthreadtofetchmoredocumentsfromtheBroker. Documentretrievalrequiresaserverthreadwithwhichtorequestandretrieve documentsfromtheBroker.Documentretrievalalsorequiresmemorybecausethe IntegrationServerkeepstemporarycopiesofthedocumentsitisretrievinginmemory. TheIntegrationServerreleasesthetemporarycopiesfrommemoryaftersuccessfully processingthedocument. TheIntegrationServerprovidescontrolsthatyoucanusetomanagetheserverresources usedfordocumentretrieval.Specifically,youcanusethecontrolsto: Limitthenumberofserverthreadsusedfordocumentretrieval. Managetherateofdocumentretrievalandtheamountofmemoryusedduring documentretrievalbyadjustingtriggerqueuecapacity. Suspendorresumedocumentretrievalforoneormoretriggers. Thesecontrolscanbeusedduringdevelopment,capacityplanning,oratruntime.The followingsectionsprovidemoreinformationaboutthesecontrols.
Increasing or Decreasing Threads for Document Retrieval

Duringproductionandcapacityplanning,youcanincreaseordecreasethenumberof threadsusedtoretrievedocumentsfromtheBroker.Bydefault,IntegrationServercan useupto100%oftheserverthreadpooltoretrievedocuments.Eachtriggerusesa separateserverthreadtoretrievedocumentsfromtheBroker.Forexample,ifthe maximumsizeoftheserverthreadpoolis80threads,andtheservercanuse100%ofthe serverthreadpooltoretrievedocuments,thenupto80triggerscanrequestmore documentsatonetime. Note: Youcanonlyspecifythreadsfordocumentretrievalifyourintegrationsolution includesaBroker. Youcanlimitthemaximumnumberofthreadsusedfordocumentretrievalbyspecifying thepercentageoftheserverthreadpoolthatcanbeusedtoretrievedocuments.The IntegrationServerusesthespecifiedpercentagetocalculatethenumberofserverthreads thatcanbeusedtoretrievedocumentsfromtheBroker. Forexample,supposethatthemaximumsizeoftheserverthreadpoolis80threads.If youspecifyamaximumdocumentretrievalthreadspercentageof10%,thenthe IntegrationServercanuseonly8threadstoretrievedocumentsatonetime.Becausethe IntegrationServerusesaseparatethreadtoretrievedocumentsforeachtrigger,this meansthattheIntegrationServercanretrievedocumentsforonly8triggersatonetime. Reducingthepercentageoftheserverthreadpoolusedfordocumentretrievalcanslow therateofdocumentretrievalbecausefewertriggerscanretrievedocuments
363
simultaneously.Italsoensurestheavailabilityofserverthreadsforothertasks,suchas answeringHTTPrequestsorprocessingdocuments. Increasingthepercentageoftheserverthreadpoolavailablefordocumentretrievalcan increasethearrivalrateofdocumentsbecauseitallowsmoretriggerstoretrieve documentsfromtheBrokeratonetime. Formoreinformationaboutsettingthenumberofserverthreadsfordocumentretrieval, seeLimitingServerThreadsforBroker/LocalTriggersonpage 379.
When to Increase or Decrease Threads for Document Retrieval

Yourknowledgeofyourintegrationsolutionisthebesttoolfordeterminingwhento increaseanddecreasethreadusagefordocumentretrieval.Forexample,ifyouknowthat theIntegrationServerregularlyreceivesahighnumberofHTTPrequestsduringa certaintimeperiod,youmightwanttodecreasethreadusagefordocumentretrieval rightbeforetheHTTPrequestsusuallybegin,thenincreasedocumentretrievalthread usageafterthefrequencyofHTTPrequestsslowsdown.Alternatively,ifyouknowthat theIntegrationServerreceivesahighvolumeofincomingdocumentsatthesametime eachday,youmightwanttoincreasethenumberofthreadsavailablefordocument retrievalduringthattimeperiod. Youcanalsodeterminewhentoincreaseordecreasethreadsfordocumentretrievalby monitoringthenumberofavailableserverthreads.Toassistwiththis,youcanestablisha warningthresholdthatinstructstheIntegrationServertoalertyouwhenthepercentage ofavailablethreadsdropsbelowaspecifiedlevel.Specifically,theIntegrationServer createsajournallogentrystatingAvailable Thread Warning Threshold Exceeded. Whenyoureceivethismessageinthejournallog,youcandecreasethreadsfordocument retrievaltomakeserverthreadsavailabletoperformotherfunctions.Formore informationaboutsettinganavailablethreadswarningthreshold,seeSwitchingfrom theEmbeddedDatabasetoanExternalRDBMSonpage 79. Anothermethodofdeterminingwhentoalterthenumberofserverthreadsallottedfor documentretrievalistomonitorthecurrentnumberofthreadsretrievingdocuments fromtheBroker.TheIntegrationServerAdministratordisplaysthisvalueintheCurrent Threads fieldunderDocument RetrievalontheSettings > Messaging > Broker/Local Trigger Managementpage. Note: Otherwaystocontroltheresourcesusedfordocumentretrievalare:adjusting triggerqueuecapacityandsuspendingorresumingdocumentretrievalfortriggers. Formoreinformationaboutadjustingtriggerqueuecapacity,seeDecreasingthe CapacityofTriggerDocumentStoresonpage 365.Formoreinformationabout suspending(orresuming)documentprocessing,seeSuspendingandResuming DocumentRetrievalonpage 366.
364
Decreasing the Capacity of Trigger Document Stores

Youcanimpacttheamountofmemoryusedfordocumentretrievalbyadjustingthe capacityandrefilllevelofallthetriggerqueues.Thecapacitydeterminesthemaximum numberofdocumentsthatthetriggerdocumentstorecancontain.Therefilllevelspecifies thenumberofdocumentsthatremaininthetriggerqueuebeforetheIntegrationServer requestsmoredocumentsfromtheBroker. YoucanusetheQueueCapacityThrottleprovidedintheIntegrationServer Administratortodecreasethecapacityandrefilllevelsofallthetriggerqueuesonthe IntegrationServer.TheQueueCapacityThrottlereducesthecapacityandrefilllevelsfor allthetriggerqueuesbythesamepercentage.Forexample,ifyousettheQueueCapacity Throttleto50%ofmaximum,atriggerqueuewithacapacityof10andarefilllevelof4 willhaveanadjustedcapacityof5andanadjustedrefilllevelof2. Bydecreasingthecapacityandrefilllevels,youcan ReducetheamountofmemoryneededtoretrievedocumentsfromtheBroker. ReducedcapacityandrefilllevelsmeanthattheIntegrationServerretrievesfewer documentsforatriggeratonetime.BecausetheIntegrationServerretrievesfewer documents,theIntegrationServeruseslessmemorywhenretrievingdocuments. Reducethememoryneededtostorethedocumentswhiletheyawaitprocessing. Note: DecreasingthecapacitymightincreasethefrequencywithwhichtheIntegration ServerretrievesdocumentsbecausetheIntegrationServermightemptythetrigger documentstoretotheadjustedrefilllevelmorequickly. To decrease the capacity and refill level of trigger queues 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickMessaging. ClickBroker/Local Trigger Management,andthenclickEdit Global Trigger Controls. UnderDocument Retrieval,intheQueue Capacity Throttlefield,selectthepercentageof configuredcapacityatwhichyouwantalltriggerqueuestooperate.TheIntegration Serverautomaticallyadjuststherefilllevelsbythesamepercentage. Ifyouwanttoapplythequeuecapacitythrottlechangetoalltheservesinacluster, selecttheApply Change Across Clustercheckbox. ThischeckboxappearsonlyifthecurrentIntegrationServerbelongstoaproperly configuredclusterandisconfiguredtosynchronizetriggerchangesacrossthecluster. FormoreinformationaboutconfiguringanIntegrationServertosynchronizetrigger managementchangesacrossacluster,seeClusterSynchronizationforTrigger Managementonpage 380. 6 ClickSave Changes.
365
Notes: TheQueueCapacityThrottlesettingismaintainedacrossserverrestartsandpackage reloads. Ifthepercentagebywhichyoureducecapacitydoesnotresolvetoawholenumber, theIntegrationServerroundsuporroundsdowntothenearestwholenumber. However,ifroundingdownwouldreducethevalueto0,theIntegrationServer roundsupto1.Forexample,ifyousettheQueueCapacityThrottleto10%of maximum,atriggerqueuewitha capacityof15andrefilllevelof4willhavean adjustedcapacityof2andanadjustedrefilllevelof1(TheIntegrationServerrounds thecalculatedadjustedcapacityof1.5upto2androundsthecalculatedadjusted refilllevelof0.4upto1). WhenyoureducetheQueueCapacityThrottleandsaveyourchanges,the IntegrationServerdoesnotimmediatelyreducethenumberofdocumentsinatrigger queue.Instead,theIntegrationServercontinuestoprocessdocumentsinthetrigger queueuntilitreachestheadjustedrefilllevel.Then,theIntegrationServerretrieves enoughdocumentstofillthetriggerqueuetotheadjustedcapacity.Forexample,if yousetQueueCapacityThrottleto50%,atriggerqueuewithacapacityof8anda refilllevelof2willhaveanadjustedcapacityof4andanadjustedrefilllevelof1.The IntegrationServerprocessesdocumentsinthetriggerqueueuntilitreachesthe adjustedrefilllevelofonly1document.Then,theIntegrationServerretrievesupto3 documentstoincreasethenumberofdocumentsinthequeueto4(theadjusted capacity). Ifyoureducethecapacitytoalowpercentageforanextendedperiodoftime,the documentmightexpireontheBroker.Foreachpublishabledocumenttype,youcan specifyaTime to liveproperty.Thispropertyspecifieshowlongadocumentcan remainontheBrokerbeforetheBrokerdiscardsit.Formoreinformationabout publishabledocumenttypes,seePublishSubscribeDevelopersGuide. IfyouusetheQueueCapacityThrottleaspartofyourcapacityplanningprocessand youdeterminethattheconfiguredvaluesfortriggercapacityandrefilllevelneedto change,youcanusetheIntegrationServerAdministratororwebMethodsDeveloper tosetthenewcapacityandrefilllevelvaluesforeachtrigger.Formoreinformation aboutsettingthecapacityandrefilllevelforatrigger,seeModifyingBroker/Local TriggerPropertiesonpage 384.
Suspending and Resuming Document Retrieval

Youcanreducetheamountofserverresourcesthatdocumentretrievalconsumesby suspendingdocumentretrievalforoneormoretriggers.UsingtheIntegrationServer Administrator,youcan: Suspendorresumedocumentretrievalforalltriggers. Suspendorresumedocumentretrievalforspecifictriggers. Thefollowingsectionsprovidemoreinformationabouttheseoptions.
366
Suspending and Resuming Document Retrieval for all Triggers

WhenyoususpenddocumentretrievalforallthetriggersonanIntegrationServer,the IntegrationServerstopsretrievingdocumentsfromtheBroker.Serverresources,suchas threadsandmemory,thatwouldhavebeenusedfordocumentretrievalareavailablefor othertasks. Suspendingdocumentretrievalglobally(foralltriggers)isaquickwayoffreeingup serverresources.ThiscanbeespeciallyhelpfulinasituationinwhichtheIntegration Serverisfunctioningunderheavyloadandadditionalresourcesareneeded immediately. Suspendingorresumingdocumentretrievalcanbeatemporaryorpermanentchange. (TheIntegrationServerconsidersadocumentretrievalchangetobepermanentifyou selectedtheApply Change Permanentlycheckboxwhenyoumadethechange.)Ifthe changeistemporary,theIntegrationServerrevertstothepermanentdocumentretrieval statewhentheIntegrationServerrestartsoryoureloadapackage.Whenyoureloada package,theIntegrationServerrevertsonlythetriggerscontainedinthatpackagetothe permanentdocumentretrievalstate.Forexample,supposethatyoutemporarilysuspend documentretrievalforalltriggers.IfyoureloadthepackageOrderProcessing,the IntegrationServerresumesdocumentretrievalforthetriggersintheOrderProcessing packageonly. Tip! OntheSettings > Messaging > Broker/Local Trigger Management pageunderDocument Retrieval,theIntegrationServerAdministratorindicatesatemporarydocument retrievalchangebydisplayinganasterisk(*)nexttothetriggerstatusintheActive column. YoucangraduallyresumedocumentretrievalbysettingtheQueueCapacityThrottletoa lowpercentage,suchas10%,andthenresumingdocumentretrievalforalltriggers.The IntegrationServerresumesdocumentretrievalattheadjustedcapacityforalltriggers. Youcanalsograduallyresumedocumentretrievalbyselectivelyresumingindividual triggers.Forexample,youmightwanttoresumedocumentretrievalforthosetriggers thatarepartofacriticalorhighpriorityprocess. To suspend or resume document retrieval for all triggers
.
1 2 3 4
OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickMessaging. ClickBroker/Local Trigger Management. UnderIndividual Trigger Controls,intheActivecolumnlocatedunderDocument Retrieval, clickedit all.
367
IntheRetrieval Statelist,dothefollowing: Select... Active Suspended To... Resumedocumentretrievalforallofthetriggersonthe IntegrationServer. Suspenddocumentretrievalforallofthetriggersonthe IntegrationServer.
IfyouwantthestatechangetobepermanentandmaintainedaftertheIntegration Serverrestartsorafterapackagereload,selecttheApply Change Permanentlycheckbox. Ifyoudonotselectthischeckbox,theIntegrationServerconsidersthechangetobe temporary. Ifyouwanttoapplythedocumentretrievalchangetoalltheserversinacluster, selecttheApply Change Across Clustercheckbox. ThischeckboxappearsonlyifthecurrentIntegrationServerbelongstoaproperly configuredclusterandisconfiguredtosynchronizetriggerchangesacrossthecluster. FormoreinformationaboutconfiguringanIntegrationServertosynchronizetrigger managementchangesacrossacluster,seeClusterSynchronizationforTrigger Managementonpage 380.
ClickSave Changes.
Notes: TheIntegrationServerdoesnotsuspend(orresume)documentretrievalifthetrigger islockedordisabled. IftheIntegrationServercannotsuspend(orresume)documentretrievallocally, clustersynchronizationcannotoccur. TheIntegrationServerdoesnotsuspend(orresume)documentretrievalfortriggers thathavebeenexcludedfromtriggermanagementchangesusingthe watt.server.trigger.managementUI.excludeList.Formoreinformationaboutthis property,seeAppendix B,ServerConfigurationParameters. SuspendingdocumentretrievalaffectsdocumentretrievalfromtheBrokeronly. Triggerswillcontinuetoreceivelocallypublisheddocuments.Additionally,triggers willcontinuetoreceivedocumentsdeliveredtothedefaultclient. Whenyoususpenddocumentretrieval,theIntegrationServerwillnotdispatchany serverthreadstoretrievedocumentsfromtheBroker.Anyserverthreadscurrently retrievingdocumentsforthetriggerwillexecutetocompletion. Whenyoususpenddocumentretrieval,documentstowhichthistriggersubscribes willcollectinthetriggersclientqueueontheBroker.Documentsremaininthe triggersclientqueueuntildocumentretrievalresumesforthetriggerorthe documentsexpire. Whenyouresumedocumentretrieval,theIntegrationServerresumesdocument retrievalforalltriggersatthepercentagespecifiedbytheQueueCapacityThrottle.
368
Ifyoudonotresumedocumentretrievalbeforetheserverrestarts,thetrigger packagereloads,orthetriggerpropertiesaremodified,theBrokerdiscardsany volatiledocumentsinthattriggersclientqueue.
Suspending and Resuming Document Retrieval for a Specific Trigger

Sometimes,insteadofsuspendingorresumingdocumentretrievalforalltriggers,you mightwanttosuspendorresumedocumentretrievalforspecifictriggers.Followingare somesituationsinwhichyoumightwanttosuspendorresumedocumentretrievalfor specifictriggers. Whenabackendsystemneedsmaintenanceorisbecomingunresponsive,youmight wanttosuspenddocumentretrievalfortriggersthatinteractwiththebackend system.Bysuspendingdocumentretrieval,documentsthatwouldnormally accumulateontheIntegrationServerawaitingprocessingremainontheBroker.This keepsmemoryandotherserverresourcesavailableforotheractivities.Whenthe backendsystembecomesavailable,youcanresumedocumentretrievalforthe associatedtriggers. Aftersuspendingdocumentretrievalforalltriggers,youmightresumedocument retrievalforspecifictriggers.Iftheserverisfunctioningunderanunusuallyheavy load,youmightfirstsuspendretrievalforalltriggersandthengraduallyresume retrieval,startingwiththetriggersinvolvedinkeyprocesses. IftheIntegrationServersuspendsdocumentretrievalforaserialtriggerbecausethe associatedtriggerserviceendsinerror,youneedtoresumedocumentretrievalfor thattrigger.Formoreinformationaboutconfiguringaserialtriggertosuspend retrievalandprocessingautomaticallyafteranerror,seethePublishSubscribe DevelopersGuide. Thefollowingprocedureexplainshowtosuspendorresumedocumentretrievalforan individualtrigger. To suspend or resume document retrieval for a trigger 1 2 3 4 5 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickMessaging. ClickBroker/Local Trigger Management. UnderIndividual Trigger Controls,locatetherowcontainingthetriggerforwhichyou wanttosuspenddocumentretrieval. IntheActivecolumnlocatedunderDocument Retrieval,clickYesorNo.(TheActive columndisplaysYesifdocumentretrievalisactiveforthetrigger;Noif documentretrievalissuspended.Anasterisk(*)appearsnexttothestatusifthe documentretrievalstateistemporary.)
369
IntheRetrieval Statelist,dothefollowing: Select... Active Suspended To... Resumedocumentretrievalforthistrigger. Suspenddocumentretrievalforthistrigger.
IfyouwantthestatechangetobepermanentandmaintainedaftertheIntegration Serverrestarts,selecttheApply Change Permanentlycheckbox.Ifyoudonotselectthis checkbox,theIntegrationServerconsidersthechangetobetemporary. Ifyouwanttoapplythedocumentretrievalchangeforthistriggertoalltheserversin acluster,selecttheApply Change Across Clustercheckbox. ThischeckboxappearsonlyifthecurrentIntegrationServerbelongstoaproperly configuredclusterandisconfiguredtosynchronizetriggerchangesacrossthecluster. FormoreinformationaboutconfiguringanIntegrationServertosynchronizetrigger managementchangesacrossacluster,seeClusterSynchronizationforTrigger Managementonpage 380.
ClickSave Changes.
Notes: TheIntegrationServerwillnotsuspendorresumedocumentretrievalforthe specifiedtriggerifthetriggerislockedbyauser. IftheIntegrationServercannotsuspend(orresume)documentretrievallocally, clustersynchronizationcannotoccur. Whenyouresumedocumentretrieval,theIntegrationServerresumesretrievalfor thetriggeratthepercentagespecifiedbytheQueueCapacityThrottle. Inaflowservice,youcansuspendorresumedocumentretrievalforindividual triggersbyinvokingthepub.trigger:suspendRetrievalserviceorthepub.trigger:resumeRetrieval service,respectively.Formoreinformationabouttheseservices,seethewebMethods IntegrationServerBuiltInServicesReference. InaJavaservice,youcansuspendorresumedocumentretrievalbycalling com.wm.app.b2b.server.dispatcher.trigger.TriggerFacade.setRetrievalSuspended(). Formoreinformationaboutthismethod,seethewebMethodsIntegrationServerJava APIReferenceforthecom.wm.app.b2b.server.dispatcher.trigger.TriggerFacadeclass. Youcanfilterthelistofdisplayedtriggersusingthe watt.server.trigger.managementUI.excludeListproperty.Formoreinformation aboutthisproperty,seeAppendix B,ServerConfigurationParameters.
370
Managing Document Processing

Withinthepublishandsubscribemodel,documentprocessingistheprocessofevaluating documentsagainsttriggerconditionsandexecutingtheappropriatetriggerservicesto actonthosedocuments.Documentprocessingrequiresaserverthreadwithwhichto evaluatethedocumentandexecutethetriggerservice.Italsorequiresmemoryinwhich tokeepacopyofthedocumentduringdocumentevaluationandtriggerservice execution. TheIntegrationServerprovidesvariouscontrolsthatyoucanusetomanagetherateof andresourcedemandsfordocumentprocessing.Specifically,youcan: Limitthenumberofserverthreadsusedfordocumentprocessing. Managethenumberofserverthreadsthatcanbeusedtoprocessdocumentsfora triggerconcurrently. Suspendorresumedocumentprocessingforoneormoretriggers. Thesecontrolscanbeusedaspartofyourcapacityplanningorusedduringproduction. Thefollowingsectionsprovidemoreinformationaboutthesecontrols.
Increasing or Decreasing Threads for Document Processing

Duringproductionandcapacityplanning,youcanincreaseordecreasethenumberof threadsthatcanbeusedtoprocessdocumentssimultaneously.Thenumberofthreads availablefordocumentprocessinghelpsdeterminetherateatwhichtheIntegration Serverprocessesdocumentsthatitreceives.Bydefault,theIntegrationServercanuseup to100%oftheserverthreadpooltoprocessdocuments(executetriggers).Eachtimethe IntegrationServerprocessesadocument,theserverusesaserverthread.Forexample,if themaximumsizeoftheserverthreadpoolis80threads,andtheservercanuse100%of theserverthreadpooltoexecutetriggers,thenupto80triggerscanexecuteatthesame time.Thatis,theIntegrationServercanprocessupto80documentssimultaneously. Youcancontrolthenumberofserverthreadsavailablefordocumentprocessing(trigger execution)byspecifyingthemaximumpercentageoftheserverthreadpoolthatcanbe usedtoexecutedocuments.TheIntegrationServerusesthepercentagetocalculatethe numberofserverthreadsthatcanbeusedfortriggerexecution(documentprocessing). Forexample,supposethatthemaximumsizeoftheserverthreadpoolis80threads.If youset10%asthemaximumpercentageofdocumentprocessingthreads,thenthe IntegrationServercanuseupto8threadstoexecutetriggersatonetime. Byreducingthenumberofserverthreadsusedforprocessingdocuments,youcanmake serverthreadsandmemoryavailabletoperformothertasks,suchasexecutingHTTP requestsandretrievingdocuments.Alternatively,youcanincreasethenumberofthreads fordocumentprocessingtoallowtheservertoprocessmoredocumentssimultaneously. Thiscanalsoallowtheservertodrainthetriggerqueuesmorequicklyandrequest additionaldocumentsmorefrequently. Documentprocessingforserialandconcurrenttriggerscombinedcannotexceedthe valuedeterminedbythemaximumdocumentprocessingthreadspercentage.Ifyou
371
reducethepercentageofdocumentprocessingserverthreads,andconcurrenttriggers continuetoconsumethemaximumexecutionthreadspossible(accordingtotheir configuredsettings),serialtriggersmustwaitlongerforserverthreadstobecome available.ThisisespeciallylikelyiftheIntegrationServercontainsconcurrenttriggers thatexecutelongrunningservices. Formoreinformationaboutsettingthenumberofserverthreadsfordocument processing,seeLimitingServerThreadsforBroker/LocalTriggersonpage 379. Tip! Ifyoudecreasethepercentageofthreadsthatcanbeusedfordocument processing,considerdecreasingtheExecutionThreadsThrottletopreventconcurrent triggersfrommonopolizingavailableserverthreads.
When to Increase or Decrease Threads for Processing Documents

Yourknowledgeofyourintegrationsolutionisthebesttoolfordeterminingwhento adjustthreadusagefordocumentprocessing(triggerexecution).Forexample,suppose thatabatchprocessthatoccursatthesametimeeachdayresultsinaspikeindocument publishing.Youmightwanttoincreasethreadsfordocumentprocessingrightbeforethe batchprocessstartstomakeserverthreadsavailabletoprocessdocuments. Alternatively,ifyouobservememoryconstraintsorotherresourceissues,youcan decreasethenumberofthreadsfordocumentprocessing.Documentprocessing consumesmemorybecausetheIntegrationServerkeepsthedocumentinmemorywhile theserverthreadevaluatesthedocumentandexecutesthetriggerservice. Youcanalsodeterminewhentomodifythenumberofthreadsallowedfordocument processingbymonitoringthreadusage.Youcandothisbyviewingthethreadusage informationdisplayedontheServer>Statisticspage.However,youcanalsoestablisha warningthresholdthatinstructstheIntegrationServertoalertyouwhenthenumberof availablethreadsdropsbelowaparticularlevel.Specifically,theIntegrationServer createsajournallogentrystatingAvailable Threads Warning Threshold Usage Exceeded.WhentheIntegrationServerwritesthisjournallogentry,youmightwantto decreasethreadsfordocumentprocessingtoallowmorethreadstobeusedforother functions.Formoreinformationaboutsettinganavailablethreadswarningthreshold, seeSwitchingfromtheEmbeddedDatabasetoanExternalRDBMSonpage 79. Anotherwaytodeterminewhentoalterthenumberofserverthreadsallottedfor documentprocessingistomonitorthecurrentnumberofthreadsthatareprocessing documentsfortriggers.TheIntegrationServerAdministratordisplaysthisvalueinthe Current ThreadsfieldlocatedunderDocument ProcessingontheSettings > Messaging > Broker/Local Trigger Managementpage. Note: Otherwaystocontroltheresourcesusedfordocumentprocessingare:adjusting executionthreadsforconcurrenttriggersandsuspendingorresumingdocument processingfortriggers.Formoreinformationaboutadjustingtriggerqueuecapacity, seeDecreasingDocumentProcessingforConcurrentTriggersonpage 373.For moreinformationaboutsuspending(orresuming)documentprocessing,see SuspendingandResumingDocumentProcessingonpage 375.
372
Decreasing Document Processing for Concurrent Triggers

Youcanreducetheamountofserverresourcesconsumedbydocumentprocessingby decreasingtherateofprocessingforconcurrenttriggers.Specifically,youcanreducethe maximumnumberofthreadsthatcanprocessdocumentsforaconcurrenttriggeratone time. TheIntegrationServerAdministratorprovidesanExecutionThreadsThrottlethatyou canusetoreducetheexecutionthreadsforallconcurrenttriggersbythesame percentage.Forexample,ifyousettheExecutionThreadsThrottleto50%ofmaximum, theIntegrationServerreducesthemaximumexecutionthreadsforallconcurrenttriggers byhalf.Aconcurrenttriggerwithamaximumexecutionthreadsvalueof6,hasan adjustedmaximumexecutionthreadsvalueof3. Bydecreasingparallelprocessingforconcurrenttriggers,youcan: Freeupserverthreadsandmemorytoperformotherfunctions,suchasanswering HTTPrequestsorretrievingdocuments. Preventconcurrenttriggersfrommonopolizingthethreadsallottedfordocument processing.Thenumberofserverthreadsthattheserverdispatchestoprocess documentsforserialandconcurrenttriggerscannotexceedthevalueestablishedby themaximumexecutionthreadspercentage.Ifyoureducethenumberofthreads allowedfordocumentprocessing,andconcurrenttriggerscontinuetoconsumethe maximumexecutionthreadspossible(accordingtotheirconfiguredsettings),serial triggersmustwaitlongerforserverthreadstobecomeavailable.Thisisespecially likelyiftheIntegrationServercontainsconcurrenttriggersthatexecutelongrunning services. To decrease parallel execution threads for concurrent triggers 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickMessaging. ClickBroker/Local Trigger Management,andthenclickEdit Global Trigger Controls. UnderDocument Processing,intheExecution Threads Throttlefield,selectthepercentage oftheconfiguredmaximumexecutionthreadsvalueatwhichyouwanttotheserver tofunction.TheIntegrationServerappliesthispercentagetothemaximumexecution threadsvalueforallconcurrenttriggers. IfyouwanttoapplytheExecutionThreadsThrottlechangetoalltheserversina cluster,selecttheApply Change Across Clustercheckbox. ThischeckboxappearsonlyifthecurrentIntegrationServerbelongstoaproperly configuredclusterandisconfiguredtosynchronizetriggerchangesacrossthecluster. FormoreinformationaboutconfiguringanIntegrationServertosynchronizetrigger managementchangesacrossacluster,seeClusterSynchronizationforTrigger Managementonpage 380. 6 ClickSave Changes.
373
Notes: TheExecutionThreadsThrottlevalueismaintainedacrossserverrestartsand packagereloads. Serialtriggersalwaysprocessonedocumentatatime.The ExecutionThreads Throttlepropertydoesnotaffectserialtriggers. Ifthepercentagebywhichyoureducetriggerexecutionthreadsdoesnotresolvetoa wholenumber,theIntegrationServerroundsuporroundsdowntothenearest wholenumber.However,ifroundingdownwouldsetthevalueto0,theIntegration Serverroundsupto1.Forexample,ifyoureduceExecutionThreadsThrottleto10% ofmaximum,aconcurrenttriggerwithamaximumexecutionthreadsvalueof12 wouldhaveanadjustedvalueof1(theIntegrationServerrounds1.2downto1).A concurrenttriggerwithamaximumexecutionthreadsvalueof4wouldhavean adjustedvalueof1(theIntegrationServerrounds0.4upto1). WhenyoureducetheExecutionThreadsThrottleandsaveyourchanges,the IntegrationServerdoesnotterminatethreadscurrentlyexecutingconcurrenttriggers tomeettheadjustedmaximum.TheIntegrationServerallowsserverthreads processingdocumentsforconcurrenttriggerstoexecutetocompletion.The IntegrationServerwaitsuntilthenumberofthreadsexecutingforaconcurrent triggerislessthantheadjustedmaximumbeforedispatchinganotherserverthreadto processadocumentforthattrigger. Ifyoususpenddocumentprocessing(triggerexecution)anddonotsuspend documentretrieval,theIntegrationServerwillfillallthetriggerqueuestocapacity. Fulltriggerqueuesconsumemorememorythanemptytriggerqueues. Youcanalsoreducethenumberofconcurrentexecutionthreadsforatriggerby reducingthecapacityofatriggerqueuebelowthemaximumnumberofconcurrent executionthreadsforthetrigger.Themaximumnumberofdispatchedthreadsfora triggercannotexceedthetriggerqueuescapacity.Formoreinformationabout reducingtriggerqueuecapacity,seeDecreasingtheCapacityofTriggerDocument Storesonpage 365. IfyouusetheExecutionThreadsThrottleaspartofyourcapacityplanningprocess andyoudeterminethattheconfiguredvaluesforMaximum execution threadsneedto change,youcanusetheIntegrationServerAdministratororwebMethodsDeveloper tosetthenewmaximumexecutionthreadsvaluesforeachconcurrenttrigger.For moreinformationaboutsettingtriggerproperties,seeModifyingBroker/Local TriggerPropertiesonpage 384.
374
Suspending and Resuming Document Processing

Youcanreducetheamountofserverresourcesthatdocumentprocessingconsumesby suspendingdocumentprocessingforoneormoretriggers.UsingtheIntegrationServer Administrator,youcan: Suspendorresumedocumentprocessingforalltriggers. Suspendorresumedocumentprocessingforspecifictriggers. Thefollowingsectionsprovidemoreinformationabouttheseoptions.
Suspending and Resuming Document Processing for all Triggers

Whenyoususpenddocumentprocessingforalltriggers,theIntegrationServerstops dispatchingserverthreadstoprocessdocumentsstoredintriggerqueues.Server resources,suchasthreadsandmemory,thatmighthavebeenusedfordocument processingwillbeavailableforothertasks.Documentprocessingremainssuspended untilyouspecificallyresumeit. Suspendingdocumentprocessingforalltriggersisaquickwaytomakeserverresources available.ThiscanbeespeciallyhelpfulinasituationinwhichtheIntegrationServeris functioningunderheavyloadandadditionalresourcesneedtobeavailableimmediately. Suspendingorresumingdocumentprocessingcanbeatemporaryorpermanentchange. (TheIntegrationServerconsidersadocumentprocessingchangetobepermanentifyou selectedtheApply Change Permanentlycheckboxwhenyoumadethechange.)Ifthe changeistemporary,theIntegrationServerrevertstothepermanentdocument processingstatewhentheIntegrationServerrestartsoryoureloadapackage.Whenyou reloadapackage,theIntegrationServerrevertsonlythetriggerscontainedinthat packagetothepermanentdocumentprocessingstate.Forexample,supposethatyou temporarilysuspenddocumentprocessingforalltriggers.Ifyoureloadthepackage OrderProcessing,theIntegrationServerresumesdocumentprocessingforthetriggersin theOrderProcessingpackageonly. Tip! OntheSettings > Messaging > Broker/Local Trigger Management pageunderDocument Processing,theIntegrationServerAdministratorindicatesatemporarydocument processingchangebydisplayinganasterisk(*)nexttothetriggerstatusintheActive column. Whenyouarereadytoresumedocumentprocessing,youmightwanttoresumeit gradually.Forexample,youmightsettheExecutionThreadsThrottletoalow percentage,resumedocumentprocessingforalltriggers,andthengraduallymovethe ExecutionThreadsThrottleupto100%.Alternatively,youmightselectivelyresume individualtriggers.Forexample,youmightwanttoresumedocumentprocessingfor thosetriggersthatarepartofacriticalorhighpriorityprocess.
375
To suspend or resume document processing for all triggers

.
1 2 3 4 5
OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickMessaging. ClickBroker/Local Trigger Management. UnderIndividual Trigger Controls,intheActivecolumnlocatedunderDocument Processing,clickedit all. IntheProcessing Statelist,dothefollowing: Select... Active Suspended To... Resumedocumentprocessingforallofthetriggersonthe IntegrationServer. Suspenddocumentprocessingforallofthetriggersonthe IntegrationServer.
IfyouwantthestatechangetobepermanentandmaintainedaftertheIntegration Serverrestarts,selecttheApply Change Permanentlycheckbox.Ifyoudonotselectthis checkbox,theIntegrationServerconsidersthechangetobetemporary. Ifyouwanttoapplythedocumentprocessingchangetoalltheserversinacluster, selecttheApply Change Across Clustercheckbox. ThischeckboxappearsonlyifthecurrentIntegrationServerbelongstoaproperly configuredclusterandisconfiguredtosynchronizetriggerchangesacrossthecluster. FormoreinformationaboutconfiguringanIntegrationServertosynchronizetrigger managementchangesacrossacluster,seeClusterSynchronizationforTrigger Managementonpage 380.
ClickSave Changes.
Notes: TheIntegrationServerwillnotsuspendorresumedocumentprocessingforalocked ordisabledtrigger. IftheIntegrationServercannotsuspend(orresume)documentprocessinglocally, clustersynchronizationcannotoccur. TheIntegrationServerdoesnotsuspend(orresume)documentprocessingfor triggersthathavebeenexcludedfromtriggermanagementchangesusingthe watt.server.trigger.managementUI.excludeList.Formoreinformationaboutthis property,seeAppendix B,ServerConfigurationParameters. Suspendingorresumingdocumentprocessingaffectsalldocumentsinthetriggers queueontheIntegrationServer,includingdocumentsretrievedfromtheBrokerand fromlocalpublishing.
376
Whenyoususpenddocumentprocessing,theIntegrationServerwillnotdispatch anymoreserverthreadstoprocessdocuments.Anyserverthreadscurrently processingdocumentsfortriggerswillexecutetocompletion.Thisincludes documentsthatarebeingretried. Whenyoususpenddocumentprocessingbutdonotsuspenddocumentretrieval, documentswillcollectintriggerqueuesuntilthetriggerqueuesareatmaximum capacityordocumentprocessingresumes.Iftheserverrestartsbeforedocument processingresumes,volatiledocumentsarediscarded. WhenyouresumedocumentprocessingtheIntegrationServerresumesdocument processingatthepercentagespecifiedbytheExecutionThreadsThrottle.
Suspending and Resuming Document Processing for Specific Triggers

Sometimes,insteadofsuspendingorresumingdocumentprocessingforalltriggers,you mightwanttosuspendorresumeprocessingforaspecifictrigger.Followingare examplesofsituationswhereyoumightwanttosuspenddocumentprocessingfor specifictriggers. Whenabackendsystembecomesunresponsiveorrequiresmaintenance,youmight wanttosuspenddocumentprocessingfortriggersthatinteractwiththatbackend system.Ifthebackendsystemisnotavailablebecauseofmaintenanceorfailure, triggerservicesthatinteractwiththesystemwouldprobablynotexecutesuccessfully. Suspendingdocumentprocessingfortheassociatedtriggersallowsformoreeffective resourceutilizationbecauseyoukeepresourcesthatwouldhavebeenusedfor unsuccessfuldocumentprocessingavailableforothertasks. Aftersuspendingdocumentprocessingforalltriggers,youmightresumedocument processingforspecifictriggers.Iftheserverisoperatingunderaheavyload,you mightfirstsuspendalldocumentprocessingandthengraduallyresumedocument processing,startingwiththetriggersinvolvedincriticalprocesses. IftheIntegrationServersuspendsdocumentprocessingforaserialtriggerbecause theassociatedtriggerserviceendsinerror,youneedtoresumedocumentprocessing forthetrigger.Formoreinformationaboutconfiguringaserialtriggertosuspend retrievalandprocessingautomaticallyafteranerror,seethePublishSubscribe DevelopersGuide To suspend or resume document processing for a trigger 1 2 3 4 5 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickMessaging. ClickBroker/Local Trigger Management. UnderIndividual Trigger Controls,locatetherowcontainingthetriggerforwhichyou wanttosuspenddocumentprocessing. IntheActivecolumnlocatedunderDocument Processing,clickYesorNo.(TheActive columndisplaysYesifdocumentprocessingisactiveforthetrigger;Noif
377
documentprocessingissuspended.Anasterisk(*)appearsnexttothestatusifthe documentprocessingstateistemporary.) 6 IntheProcessing Statelist,dothefollowing: Select... Active Suspended 7 To... Resumedocumentprocessingforthistrigger. Suspenddocumentprocessingforthistrigger.
IfyouwantthestatechangetobepermanentandmaintainedaftertheIntegration Serverrestarts,selecttheApply Change Permanentlycheckbox.Ifyoudonotselectthis checkbox,theIntegrationServerconsidersthechangetobetemporary. Ifyouwanttoapplythedocumentprocessingchangeforthistriggertoalltheservers inacluster,selecttheApply Change Across Clustercheckbox. ThischeckboxappearsonlyifthecurrentIntegrationServerbelongstoaproperly configuredclusterandisconfiguredtosynchronizetriggerchangesacrossthecluster. FormoreinformationaboutconfiguringanIntegrationServertosynchronizetrigger managementchangesacrossacluster,seeClusterSynchronizationforTrigger Managementonpage 380.
ClickSave Changes.
Notes: TheIntegrationServerwillnotsuspendorresumedocumentprocessingforthe specifiedtriggerifthetriggerislockedbyauser. IftheIntegrationServercannotsuspend(orresume)documentprocessinglocally, clustersynchronizationcannotoccur. Whenyouresumedocumentprocessingforaconcurrenttrigger,theExecution ThreadsThrottledeterminesthemaximumnumberofdocumentsthatcanbe processedinparallel. Inaflowservice,youcansuspendorresumedocumentprocessingforindividual triggersbyinvokingthepub.trigger:suspendProcessingserviceorthe pub.trigger:resumeProcessingservice,respectively.Formoreinformationaboutthese services,seethewebMethodsIntegrationServerBuiltInServicesReference. InaJavaservice,youcansuspendorresumedocumentretrievalbycalling com.wm.app.b2b.server.dispatcher.trigger.TriggerFacade.setProcessingSuspended(). Formoreinformationaboutthismethod,seethewebMethodsIntegrationServerJava APIReferenceforthecom.wm.app.b2b.server.dispatcher.trigger.TriggerFacadeclass. Youcanfilterthelistofdisplayedtriggersusingthe
watt.server.trigger.managementUI.excludeListproperty.Formoreinformation
aboutthisproperty,seeAppendix B,ServerConfigurationParameters.
378
Limiting Server Threads for Broker/Local Triggers

IntegrationServerprovidesparametersthatyoucanusetolimithowmanythreadsinthe serverthreadpoolretrieveandprocessdocumentsforBroker/localtriggers.Youcan specifywhatpercentageoftheserverthreadpoolcanbeusedtoretrievedocumentsfrom theBroker.Youcanalsospecifythepercentageoftheserverthreadpoolthatcanbeused toprocessdocuments. Forexample,supposethattheserverthreadpoolcancontainupto80threads.Ifyou specifythatthemaximumthreadsfordocumentretrievalis50%oftheserverthread pool,thentheIntegrationServercanuseupto40threadsforretrievingdocuments. Limitingthenumberofserverthreadsthatcanretrieveandprocessdocumentskeeps otherserverthreadsavailabletoperformotherserverfunctionssuchasrespondingto httprequestsorserveradministration.Theseparametershelptoensurethatdocument retrievalandprocessingwillnotmonopolizetheentireserverthreadpool. Note: WhentheIntegrationServerusesathreadfordocumentretrieval,thethread retrievesdocumentsforonetriggerfromtheBroker.Thethreaddoesnotretrieve documentsforalltriggers.Athreadusedfordocumentprocessingaddressesone documentinatriggerqueue.(Documentprocessingincludesdeterminingwhich triggerconditionthedocumentsatisfiesandexecutingtheassociatedservice.) Keepthefollowingpointsinmindwhenspecifyingthenumberofthreadsforretrieving andprocessingdocuments: Ifyouwanttoallowalltriggerstoretrievedocumentssimultaneously,setthe maximumthreadsfordocumentretrievaltoapercentagethatequatestothetotal numberoftriggers.Thatis,thenumberofthreadssetbythispercentageshouldbe equaltothetotalnumberoftriggersontheIntegrationServer. IfyouwanttoallowtheIntegrationServertoprocessthemaximumnumberof documentsatonetime,setthemaximumthreadsfordocumentprocessingtoa percentageequivalenttothenumberofserialtriggersplusthesumofmaximum concurrentthreadsforallconcurrenttriggers.Forexample,supposethatthe IntegrationServercontains10serialtriggersand10concurrenttriggersthatcaneach executeupto5threads.ToconfiguretheIntegrationServertodispatchenough threadstoprocessthemaximumnumberofdocumentsatonetime,thepercentageof threadsfordocumentretrievalshouldbeequivalentto60threads(10serialtriggers+ 5threadseachfor10concurrenttriggers). To set the maximum number of server threads for Broker/local triggers 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickMessaging. ClickBroker/Local Trigger Management,andthenclickEdit Global Trigger Controls.
379
UnderDocument Retrieval,intheMaximum Threadsfield,typethemaximumpercentage oftheserverthreadpoolthatcanbeusedtoretrievedocumentsfromtheBroker.You mustenteravaluegreaterthanzero.Thedefaultis100%. IftheMaximumThreadsfieldunderDocumentRetrievaldisplays(BrokerNot Configured),thenthisIntegrationServerisnotconfiguredtoconnecttoaBroker.
UnderDocument Processing,intheMaximum Threadsfield,typethemaximum percentageoftheserverthreadpoolthatcanbeusedtoprocessdocumentsintrigger documentstores.Youmustenteravaluegreaterthanzero.Thedefaultis100%. ClickSave Changes.
Notes: TheIntegrationServerusesthepercentagesyouenteredtocalculatethenumberof threadsthatcanbedevotedtodocumentretrievalanddocumentprocessing.Ifthe numberofthreadsdoesnotevaluatetoawholenumbertheIntegrationServer roundsupordowntothenearestwholenumber. Fordocumentretrieval,ifthecurrentnumberofserverthreadsretrievingdocuments isgreaterthanthenewvaluesetbytheMaximum Threadspercentage,theIntegration Serverwillnotdispatchmorethreadsfordocumentretrieval.Threadscurrently retrievingdocumentswillexecutetocompletion.TheIntegrationServerwilldispatch newthreadsfordocumentretrievalonlywhenthecurrentnumberofdocument retrievalthreadsislessthanthemaximumalloweddocumentretrievalthreads. Fordocumentprocessing,ifthecurrentnumberofserverthreadsprocessing documents(executingtriggers)isgreaterthanthethreadvaluedeterminedbythe Maximum Threadspercentage,theIntegrationServerwillnotdispatchmorethreadsfor documentprocessing.Threadscurrentlyprocessingdocumentswillexecuteto completion.TheIntegrationServerwilldispatchnewthreadsfortriggerexecution onlywhenthecurrentnumberofdocumentprocessingthreadsislessthanthe maximumalloweddocumentprocessingthreads. Thecurrentnumberofthreadsandmaximumallottedthreadsfordocumentretrieval anddocumentprocessingarevisibleundertheGlobal Trigger Controls headingonthe Settings > Messaging > Broker/Local Trigger Managementpage.
Cluster Synchronization for Trigger Management

IftheIntegrationServerisamemberofacluster,changesthatyoumakefordocument retrieval,documentprocessing,andfortriggerpropertiescanbepropagatedtoother serversintheclusterautomatically.Propagatingthechangestootherserversinthe clusterpreventsyoufromneedingtomakeidenticalchangesonalltheserversmanually. Itcanalsopreventtheotherserversfromabsorbingtheresourcedemandsthatwould havebeendirectedtothefirstserver. Note: Triggermanagementchangesmadeusingthepub.triggerservicescanalsobe appliedacrossacluster.
380
Configuring Cluster Synchronization

TheIntegrationServerpropagatestriggermanagementchangestoothermembersofa clusterbyperformingaremoteinvoke.Forclustersynchronizationtosucceed,youneed tocompletethefollowingtasks: Configurethecluster.TheIntegrationServercanpropagatetriggermanagement changestootherserversonlyifalltheserversaremembersofaproperlyconfigured cluster.Formoreinformationaboutconfiguringacluster,seethewebMethods IntegrationServerClusteringGuide. Setupremoteserveraliasesfortheserversinthecluster.Formoreinformationabout settingupaliasesforremoteservers,seeSettingUpAliasesforRemoteIntegration Serversonpage 68. Updatethewatt.server.cluster.aliasListpropertywithacommaseparatedlistof theremoteserveraliasnames.TheIntegrationServerusesthislistwhenexecuting theremoteinvokesthatupdatetheotherclusternodes. Note: IntegrationServersthatbelongtotheclusterbutarenotinthislistwillnot beupdatedduringclustersynchronization. Whenclustersynchronizationpropertywatt.server.cluster.aliasListisproperly configured,theApply Change Across Clustercheckboxwillbevisiblewhenperforming triggermanagementtasks.
Cluster Synchronization at Run Time

Atruntime,theIntegrationServerusesremoteinvokestoupdatetheothermembersofa clusterwithtriggermanagementchanges.Ifaremoteinvoketoaserverfailsorthat serverisnotavailableatthetimeoftheremoteinvoke,theclusterwillbeoutofsync.The IntegrationServerexecutingtheremoteinvokedisplaysthefollowingjournallog messagestoindicatethestatusoftheclustersynchronizationattempt.
381
If synchronization... Succeeds Succeedsforsome servers,butfailsfor others
Expect this log message... TheIntegrationServerAdministratordisplaysthemessage:

Settings changed successfully.
TheIntegrationServerAdministratordisplaysthemessage:
[ISS.0085.9203] Errors occurred while updating remote aliases (x of y updates failed). See server logs for more details.
Theserverlogdisplaysthemessageforeachmemberofthe clusterthatwasnotsuccessfullyupdated:
[ISS.0098.0107E] Error occurred during cluster invoke: Alias = remoteAliasName; Service = serviceName; Exception = exceptionName
YoucanusetheIntegrationServerAdministratortoviewand changeclustersynchronizationstatusfortriggers. Failsbecausethe localupdatefailed TheIntegrationServerAdministratordisplaysthemessage:

[ISS.0085.9204] Local update failed: Exception providing reason for failure. (Note: The cluster synchronization will not run until all local errors are resolved.)
Ifthetriggermanagementchangecannotbecompletedonthe localIntegrationServer,clustersynchronizationcannotoccur. Forexample,ifyoususpenddocumentretrievalforalltriggers andonetriggeriscurrentlylocked,theIntegrationServercan suspenddocumentretrievalforeverytriggerexceptthelocked one.Becausedocumentretrievalcouldnotbecompletedlocally, theIntegrationServercannotsynchronizethechangewiththe restofthecluster. Failsbecauseitis notconfigured Theserverlogdisplaysthefollowingmessage:
[ISS.0033.0156W] Cluster invoke did not complete successfully. Cluster Synchronization feature is not configured.
Formoreinformationaboutconfiguringclustersynchronization fortriggers,seeConfiguringClusterSynchronizationon page 381.
382
Monitoring Cluster Synchronization

TheIntegrationServerAdministratorprovidesaclusterviewthatyoucanusetoseethe triggersynchronizationstatusacrossalltheserversinthecluster.Foreachserverlistedin thewatt.server.cluster.aliastListproperty,theclusterviewindicateswhetherthe otherserversinthecluster(anditstriggers)areinsyncwithcurrentserver.Thecluster viewislocatedontheSettings > Messaging > Broker/Local Trigger Management>Cluster View page. Note: TheCluster ViewpageappearsonlyifthecurrentIntegrationServerbelongstoa properlyconfiguredclusterandtheserverisconfiguredtosynchronizetrigger changesacrossthecluster. Cluster View for Trigger Synchronization
Ifatriggerisnotsynchronized,theclusterviewdisplaysanerrormessagethatindicates howthetriggerisoutofsyncwiththetriggeronthecurrentserver.Forexample,if documentprocessingforatriggerissuspendedlocally,butactiveonanotherserverinthe cluster,theerrormessagenexttotriggernamestatesProcessingStatemismatch [local=suspended;remote=active]. TheIntegrationServerconsidersatriggeronaremoteservertobeoutofsyncwiththe localtriggerofthesamenameifeitherofthefollowingistrue: Thetriggershavedifferentvaluesfortriggerqueuecapacity,refilllevel,ormaximum executionthreads. Thetriggershavedifferentdocumentretrievalordocumentprocessingstates. Note: Tologontoaremoteserverinthecluster,clicktheserveraliasintheRemote Server Aliascolumn.Whenconnecting,theremoteserverpromptsyouforuserand passwordinformation.IfyouareconnectingtotheremoteserverviaHTTPSandthe HTTPSportrequirescertificates,youneedtoimportatrustedcertificateintothe browsersothatitcanbepresentedatconnectiontime.Ifthetrustedcertificatesare notimportedintothebrowser,whenyoutrytoconnecttotheremoteserver,youwill receiveamessageinformingyouthatthepageisnotavailable.Formoreinformation aboutclientauthenticationandcertificates,seeChapter 13,AuthenticatingClients.
383
Modifying Broker/Local Trigger Properties

Duringcapacityplanningorproduction,youmightdecidethattheconfiguredtrigger propertiesneedtobereset.Forexample,youmightdeterminethattheIntegrationServer performsdocumentretrievalmoresmoothlyforsometriggerswhenthetriggersqueue capacityoperatesat80%ofitsconfiguredvalue.UsingtheIntegrationServer Administrator,youcanresettheconfiguredcapacityforthosetriggers.Infact,any triggerpropertythataffectsthreadormemoryusagefordocumentretrievalordocument processingcanbesetusingtheIntegrationServerAdministrator.Theseproperties includetriggerqueuecapacity,refilllevel,andmaximumexecutionthreads. To modify trigger properties 1 2 3 4 5 6 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickMessaging. ClickBroker/Local Trigger Management. UnderIndividual Trigger Controls,clickthenameofthetriggerforwhichyouwantto editproperties. ClickEdit Trigger Properties. UnderProperties,dooneormoreofthefollowing: For this property... Queue Capacity Queue Refill Level Specify... Themaximumnumberofdocumentsthatthetriggerqueue cancontain. Thenumberofunprocesseddocumentsthatmustremainin thistriggerqueuebeforetheIntegrationServerretrieves moredocumentsforthequeuefromtheBroker. Note: TheQueue Refill levelvaluemustbelessthanorequalto theQueue Capacityvalue. Max Execution Threads ThemaximumnumberofdocumentsthattheIntegration Servercanprocessconcurrently.Youcanonlyspecifya maximumexecutionthreadsvalueforconcurrenttriggers. ThisfielddisplaysN/Aforserialtriggers.
Formoreinformationandguidelinesforsettingtriggerqueuecapacity,refilllevel, andmaximumexecutionthreads,seethePublishSubscribeDevelopersGuide.
384
Ifyouwanttoapplythepropertychangesforthistriggertoalltheserversinacluster, selecttheApply Change Across Clustercheckbox. ThischeckboxappearsonlyifthecurrentIntegrationServerbelongstoaproperly configuredclusterandisconfiguredtosynchronizetriggerchangesacrossthecluster. FormoreinformationaboutconfiguringanIntegrationServertosynchronizetrigger managementchangesacrossacluster,seeClusterSynchronizationforTrigger Managementonpage 380.
ClickSave Changes. Note: Youcanfilterthelistofdisplayedtriggersusingthe watt.server.trigger.managementUI.excludeListproperty.Formoreinformation aboutthisproperty,seeAppendix B,ServerConfigurationParameters
385
386
24
Using Integration Server to Manage XA Transactions

388 392 395
Overview of XA Transaction Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring XA Options in Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Manually Resolving a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
387
24 Using Integration Server to Manage XA Transactions
Overview of XA Transaction Management

Atransactionisalogicalunitofwork,composedofmanydifferentprocesses,thateither entirelysucceedsorhasnoeffectatall. Becausetheworkbeingperformedwithinatransactioncanoccuronmanydifferent platformsandcaninvolvemanydifferentresourcesfromdifferentvendors,theX/Open organizationdevelopedthedistributedtransactionprocess(DTP)modelandtheXA interface. TheDTPmodeldefinescommunicationamongthefollowing: Resourcessuchasdatabases. Resourcemanagerssuchasdatabaseservers.Resourcemanagersprovideaccessto sharedresources. Atransactionmanager.Thetransactionmanagercoordinatesandcontrolsall transactionsforresourcesthroughtheirresourcemanagers.IntegrationServer containsatransactionmanagersubsystemthatcoordinatesandcontrolsdatabase transactionsthatareinitiatedbythewebMethodsJDBCAdapterorthewebMethods JMSAdapter. TheXAinterfacedescribestheprotocolfortransactioncoordination,commitment,and recoverybetweenresourceandatransactionmanager.InaccordancewiththeXA specification,IntegrationServermanagestransactionsusingthetransactionprotocol calledtwophasecommit,or2PC. Inthefirstphaseof2PC,IntegrationServer(specifically,thetransactionmanager)asks theresourcesthatareparticipatinginatransactionwhethertheyarepreparedtocommit thetransaction.Inthesecondphase,oneofthefollowingoccurs: Alltheresourcesrespondthattheyarepreparedtocommit.IntegrationServer instructstheresourcestocommitthetransaction. Oneormoreresourcesrespondthattheyarenotpreparedtocommit.Integration Serverinstructsallresourcestorollbacktheirpreparationsforcommittingthe transaction.
How the Integration Server Persists the State of a Transaction

Atthebeginningofatransaction,IntegrationServercreatesauniquetransactionID calledanXID.TheIntegrationServerstorestheXIDandtheglobalstateofthe transactioninapersistentstorecalledtheXArecoverystore.Atthebeginningofeach subsequentactiontakenforthetransaction,IntegrationServerstorestheglobalstateof thetransactionandthestateofeachresourcethatisparticipatinginthetransactioninthe XArecoverystore.IfIntegrationServerendsabnormally,IntegrationServercanretrieve thestateinformationfromtheXArecoverystoreandtrytoresolveuncompleted transactions,ifthereareany.
388
ForIntegrationServertostorestateinformation,thefollowingconditionsmustbemet: ThetransactioninvolvesmultipleresourcesandalltheresourcesareXAenabled (thatis,theresourcescomplywiththeJTAandXAspecificationsandkeeppersistent recordsoftransactionsthathavebeenpreparedorheuristicallycommitted). ThetransactionisdefinedasanXAtransaction.Forexample,ifthetransaction involvesthewebMethodsJDBCadapter,thetransactionwouldbedefinedasanXA transactionontheadaptersconnectionstotheresources. Note: Aswithmostfeaturesthatimprovereliabilityandrecoverability,thisfeature mayincreasetheoverheadassociatedwithprocessingXAtransactions.
How the Integration Server Resolves Uncompleted Transactions

IfIntegrationServerendsabnormallywhiletransactionsareinprogress,those transactionsareuncompleted.WhenIntegrationServerrestarts,itretrievesalistof uncompletedtransactionsfromtheXArecoverystore.Basedonthelaststatus IntegrationServerloggedforthetransactionsonthelist,IntegrationServertriesto resolveeachtransaction,asfollows: If... Theresourceshadbegunthecommitprocessand atleastoneresourcehadcommittedthe transaction Theresourceshadfinishedpreparingtocommit thetransactionbuthadnotbegunthecommit process Theresourceshadbegunthecommitprocessbut noresourcehadcommittedthetransaction Theresourceshadbegunbutnotcompleted rollingbackthetransaction IntegrationServerhadnotyetaskedtheresources whethertheyarepreparedtocommitthe transaction Theresourceshadcompletedcommittingor rollingbackthetransaction Integration Server does this... Triestogettheotherresourcesto commit Tellstheresourcestorollbackall preparationsforthecommit Tellstheresourcestorollbackall preparationsforthecommit Tellstheresourcestorollbackall preparationsforthecommit Forgetsthetransactionanderases itsXIDfromtheXArecovery store Forgetsthetransactionanderases itsXIDfromtheXArecovery store
IfanerroroccurswhileIntegrationServeristryingtoresolveanuncompleted transaction,IntegrationServerwaitsaperiodoftimethatyouspecifyandthentries again.IntegrationServercontinuestryingtoresolvetheuncompletedtransactionuntila maximumrecoverytimethatyouspecifyexpires.Formoreinformationabout configuringthesevalues,seeConfiguringXAServerParametersonpage 394.
389
Note: NewXAtransactionscontinueunimpededduringIntegrationServersattempts atresolution. IntegrationServercannotresolvealluncompletedtransactions.Forexample,Integration Servercannotresolveatransactioninthesecases: Aresourceadministratorforcedacommitorrollbackofatransactiononaresource afterIntegrationServerendedabnormally. Thetransactionincludesa1PC(onephasecommit)resource,andIntegrationServer storesstatusesonlyfortransactionswhoseparticipatingresourcesareallXAenabled. IntegrationServercannotconnecttotheresourceafterrepeatedattemptswithinthe specifiedmaximumrecoverytime(forexample,becausethetransactioninvolvesthe webMethodsJDBCAdapterandtheadaptersconnectiontotheresourcedoesnot existorhasbeenchanged). Insuchcases,youwillhavetoresolvetheuncompletedtransactionmanually.
About Unresolved XA Transactions

IntegrationServerdisplaystheXAtransactionsthatneedtobemanuallyresolvedonthe Settings > Resources > XA Manual Recoveryscreen.IntegrationServerliststheunresolved transactioninatableanddisplaysthefollowinginformationabouteachunresolved transaction. Column XID Description UniqueXIDforthetransaction.TheXIDconformstothe javax.transaction.xa.XidinterfacedefinedintheJTAspecification. IntegrationServercreatedtheXIDatthebeginningofthe transactionandwroteittotheXArecoverystore;Integration ServeralsoprovidedtheXIDtotheparticipatingresources,which alsostoredtheinformation. GlobalstateofthetransactionbeforeIntegrationServerended.If astatemapstoaglobalstateinthejavax.transaction.Status interfacedefinedintheJTAspecification,thatmappingisshown below. State TR_PREPARE_BEGIN TR_PREPARE_RESOURCE TR_PREPARE_RESOURCE_END TR_PREPARE_END TR_COMMIT_BEGIN TR_COMMIT_RESOURCE STATUS_PREPARED STATUS_COMMITTING Description STATUS_PREPARING
Global 2PC State
390
Column
Description TR_COMMIT_RESOURCE_END TR_ROLLBACK_BEGIN TR_ROLLBACK_RESOURCE TR_ROLLBACK_RESOURCE_END TR_ROLLBACK_END TR_ROLLBACK_ONLY TR_FORGET_RESOURCE TR_FORGET_RESOURCE_END TR_COMPLETED TR_RECOVERY TR_UNDEFINED IntegrationServeristrying toresolvethetransaction. STATUS_UNKNOWN STATUS_ROLLED_BACK MARKED_ROLLBACK STATUS_ROLLING_BACK
Error Message
ErrormessagethatIntegrationServerwrotetotheserverlog beforestoringtheglobalstateofthetransactionintheXArecovery store. ActionthatIntegrationServertooktotrytoresolvethetransaction. IfGlobal 2PC StateisTR_COMMIT_BEGIN,IntegrationServertried tocommitthetransaction.Iftheglobalstateisanyothervalue, IntegrationServertriedtorollbackthetransaction.
Recovery Action Attempted
Note: Refreshthepageatintervalstomakesurealluncompletedtransactionsare listed.SupposeIntegrationServertriestoresolveanuncompletedtransactionbut cannot;thetransactionwillnotbelistedwhileIntegrationServeristryingtoresolve it,butifyourefreshthepagelater,thetransactionwillappearonthelist
Details for an Unresolved XA Transaction

ForeachunresolvedXAtransaction,youcanviewdetailedinformation,suchasthe participatingresources,thestateofthetransactiononeachresource,andtheinferred statusofthetransactionontheresource.WhenyouclicktheXIDforanunresolved transactionontheSettings > Resources > XA Manual Recoveryscreen,theIntegrationServer Administratordisplaysthefollowinginformationforeachresourceinvolvedinthe transaction:
391
Column XA Resource XID Exists?
Description Fullyqualifiednameoftheresource. IndicateswhetherthetransactionsXIDexistsontheresource. This... Yes No Unknown Indicates... ThattheXIDexistsontheresource. ThattheXIDdoesnotexist. ThattheIntegrationServercouldnotdetermine whethertheXIDexistsontheresource.
State
Currentstateofthetransactionontheresource.Thevaluesarethe sameasthoseintheGlobal 2PC Statelist.Foralistofglobal2PC states,seethetableinAboutUnresolvedXATransactionson page 390. Assumedstatusofthetransactionontheresource,basedonthe valuesofXID existsandState.Basedonthepossiblecombinations, statusesareasfollows: XID Exists? Yes No No No State Any TR_ROLLBACK_ RESOURCE_END TR_FORGET_ RESOURCE_END Anythingotherthan TR_ROLLBACK_ RESOURCE_ENDor TR_FORGET_ RESOURCE_END Inferred Status Prepared,orheuristic actionwastaken Rolledback Forgotten Committed
Inferred Status
Forinformationaboutmanuallyresolvingtransactions,seeManuallyResolvinga Transactiononpage 395.
Configuring XA Options in Integration Server

UsingIntegrationServer,youcanconfigurethefollowingoptionsforXA: EnablingordisablingXAtransactionrecovery. ThelocationandinitialsizeoftheXArecoverystore.
392
Serverparametersthatdetermine: ThelengthoftimethatIntegrationServerwaitsbetweenattemptstoresolvea transaction. Themaximumtimeallowedtoresolveatransaction. WhetheratransactionshouldcontinueifIntegrationServercannotstorethe statusofatransactionanditsparticipatingresourcesintheXArecoverystore(for example,becausethestoreiscorrupted). Thefollowingsectionsprovidemoreinformationaboutsettingtheseoptions.
Enabling or Disabling XA Transaction Recovery

YoucanenableordisableXAtransactionrecovery.WhenyoudisableXAtransaction recovery,IntegrationServerdoesnotattempttorecoverincompletetransactions automatically.Additionally,youcannotuseIntegrationServerAdministratortorecover incompletetransactionsmanually. IfyouarewillingtoexchangereliabilityandrecoveryofXAtransactionsinreturnfor possibleimprovedprocessingperformance,youmightwanttodisableXAtransaction recovery.Bydefault,IntegrationServerenablesXAtransactionrecovery. To enable or disable XA transaction recovery 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen InIntegrationServerAdministrator,gotoSettings > ResourcesandclickXA Manual Recovery. Dooneofthefollowing: IfXAtransactionrecoveryiscurrentlyenabledandyouwanttodisableit,click Disable XA Transaction Recovery.IntegrationServerAdministratorhidesthe Unresolved XA Transaction table. IfXAtransactionrecoveryiscurrentlydisabledandyouwanttoenableit,click Enable XA Transaction Recovery.IntegrationServerAdministratordisplaysthe Unresolved XA Transaction table Tip! Youcanalsousethewatt.server.jca.transaction.writeRecoveryRecordserver parametertoenableordisableXAtransactionrecovery.Formoreinformationabout settingserverparameters,seeAppendix B,ServerConfigurationParameters.
393
Configuring the XA Recovery Store

TheXArecoverystoreisapersistentstorethatcontainstheXIDandglobalsateofa transaction.YoucanspecifythelocationoftheXArecoverystoreandtheinitialsizeof thefileatstartup. To configure the XA recovery store 1 GotoSettings > Resources andclickStore Settings.IntheXA Recovery Store section, IntegrationServerAdministratorshowsthecurrentsettingsforthelocationoftheXA recoverystoreanditsinitialsize. ClickEdit XA Recovery Store Settings. IntheStore Locationfield,typetherelativeorabsolutepathtothedirectoryinthefile systeminwhichtostoretheXArecoverystorefile.Thedefaultlocationis: IntegrationServer_directory\XAStore Important! Makesurethatyouhavewriteaccesstothespecifieddirectoryandthat thedirectorydoesnotcontainanycharactersconsideredillegalbyyouroperating system. 4 IntheInitial Store Size(MB) field,typetheinitialsizefortheXArecoverystorefile,in megabytes.Thedefaultis10MB. Note: MakesurethatthereisenoughfreediskspaceontheIntegrationServer machinetoaccommodatetheinitialsizesofthedefaultdocumentstore,the triggerdocumentstore,andtheXArecoverystore. 5 ClickSave Changes. WhenyounextrestartIntegrationServer,itwillcreateanewXArecoverystorefilein thenewlocationandstartwritingtoit.IntegrationServerwillalsousethenewinitial sizeforthefile.
2 3
Configuring XA Server Parameters

IntegrationServerprovidesthefollowingserverparametersforXAtransactionsandXA transactionrecovery. watt.server.transaction.recovery.sleepInterval IfanerroroccurswhileIntegrationServeristryingtoresolveanuncompleted transaction,specifiestheperiodoftimeIntegrationServerwaitsbetweenresolution attempts. watt.server.transaction.recovery.abandonTimeout Specifiesthemaximumrecoverytimeforresolvingthetransaction.IntegrationServer continuestryingtoresolvethetransactionuntilthemaximumrecoverytimeexpires.
394
watt.server.jca.transaction.rollbackOnWriteFailure SpecifieswhetherIntegrationServershouldcontinuewithatransactionorrollitbackif IntegrationServercannotstorethestatusofatransactionanditsparticipatingresources intheXArecoverystore(forexample,becausethestoreiscorrupted).Settingthe parametertofalseinvolvessomerisk;ifIntegrationServerendsabnormally,nostatuses willhavebeensavedtotheXArecoverystore,andIntegrationServerwillnotbeableto resolvetheuncompletedtransactionorgiveyouthechancetoresolveitmanually. Formoreinformationabouttheseandotherserverparameters,seeAppendix B,Server ConfigurationParameters.
Manually Resolving a Transaction

IfIntegrationServercannotresolveatransaction,youcantrytoresolveitmanually.To successfullyresolveatransactionmanually,youmustbefamiliarwiththeparticipating resourcesandmustactinawaythatleavesthetransactioninaconsistentstate.For example,ifonlyoneoftheparticipatingresourcescommittedthetransaction,youcantry togettheotherparticipatingresourcestocommitaswell Whenyoumanuallyresolveatransaction,resolutionisnotitselfatransaction;thatis, eachparticipatingresourceandtheactionyouperformonitdoesnotparticipateinanew 2PCtransaction.Youmustthereforemakesureyouractionsresultinaconsistentstatefor theparticipatingresources. To manually resolve an XA transaction 1 2 OpentheIntegrationServerAdministratorifitisnotalreadyopen InIntegrationServerAdministrator,gotoSettings > ResourcesandclickXA Manual Recovery.IntegrationServerAdministratordisplaysalloftheunresolvedXA transactions.Foradescriptionoftheinformationdisplayedforeachunresolved transaction,seeAboutUnresolvedXATransactionsonpage 390. Note: Refreshthepageatintervalstomakesurealluncompletedtransactionsare listed.SupposeIntegrationServertriestoresolveanuncompletedtransactionbut cannot;thetransactionwillnotbelistedwhileIntegrationServeristryingto resolveit,butifyourefreshthepagelater,thetransactionwillappearonthelist 3 IntheXIDcolumn,clicktheXIDforthetransactionthatyouwanttoresolve.The IntegrationServerAdministratordisplaysdetailedinformationabouttheresources involvedinthetransaction.Foradescriptionoftheinformationdisplayedforeach participatingresource,seeDetailsforanUnresolvedXATransactiononpage 391. Ifyouwanttodeletethetransaction,clicktheDelete Transactionlink.Deletingthe transactionremovesthetransactionfromtheXArecoverystore.
395
Youmightwanttosimplydeleteatransactionifyoudonotwanttoresolvea transactionusingIntegrationServerAdministrator(forexample,becauseyouwantto resolvethetransactionbyworkingwiththeresourcesdirectly). 5 IfyouwanttoresolvethetransactionusingIntegrationServerAdministrator,select oneofthefollowingintheDesired Actioncolumn. If you want to... Youwanttocommitthetransactionontheresource Youwanttorollbackthetransactionontheresource Theresourceadministratorheuristicallycommittedor rolledbackthetransaction,soyouwanttoerasetheXID fromtheresource Theresourceadministratorhasalreadytakenthecorrect actionontheresourcesoyouneedtakenone,orthe resourceisdownforanextendedperiod Select... Commit Roll back Forget
Do nothing
Note: TheDesired Actioncolumnliststhepossibleactionsforeachresource,based onthecombinationofthevaluesforStateandXIDfortheresource,andselectsthe mostlogicalactionbydefault. 6 ClickPerform Action.IntegrationServerAdministratorreturnstotheXA Manual Recoveryscreenandremovesthetransactionfromthelistofunresolvedtransactions. IntegrationServermightreceiveanddisplayanerrorfromaresource.Errorscan occurforthesereasons: TheresourcewasnotconnectedtoIntegrationServer,probablybecausethe resourcewasdown. Theresourcehasnoknowledgeofthetransaction,possiblybecauseitlostthe2PC transactioninformation. Theresourcethrewanexception. ThetransactioninvolvedawebMethodsadapter,andIntegrationServercannot locatetheresourcebecausesomeonedeletedorchangedtheadapterconnection nodethatpointedtotheresourcefromwebMethodsDeveloper. Youmighthavetoforcethetransactiontoaconsistentstateusingthetoolsavailable ontheresourceitself.
396
Integration Server Deployment Checklist

398 398 399 400 401 402 402 403 404 405
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Stage 1: Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Stage 2: Basic Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Stage 3: Setting Up Users, Groups, and ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Stage 4: Publishing Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Stage 5: Installing Run-Time Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Stage 6: Preparing Clients for Communication with the Server . . . . . . . . . . . . . . . . . . . . . . . . . . Stage 7: Setting Up Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Stage 8: Startup and Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Stage 9: Archive Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
397
A Integration Server Deployment Checklist
Introduction
ThisappendixcontainsausefulchecklistforsettingupyourwebMethodsIntegration Server.ItdescribesthestepstoperformtoputanIntegrationServerintoproduction.The processiscomprisedofseveralstages.Youshouldcompleteonestagebeforeadvancing tothenext.
Stage 1: Installation
Completethefollowingstepstoinstall,run,andtesttheIntegrationServer. Step 1 Action Install the Integration Server. Forinstructions,seethewebMethods InstallationGuide. Note: YoucaninstalltheIntegrationServeraseitheraWindows applicationoraWindowsservice.Afterinstallation,ifyouwant,you canswitchfromaWindowsapplicationtoaWindowservice,orvice versa.Forinstructions,seeChangingWhethertheIntegrationServeris aWindowsApplicationorWindowsServiceonpage 33. 2 Change default passwords.UsetheIntegrationServerAdministratorto assignnewpasswordstothefollowinguseraccounts: TheAdministratoruseraccount. TheDeveloperuseraccount. TheCentraluseraccount. TheReplicatoruseraccount. Forinstructionsonhowtochangepasswords,refertoChanging PasswordsandPasswordRequirementsonpage 50. UsetheIntegrationServerAdministratortoassignanewmaster passwordfortheIntegrationServertousewhenencryptingoutbound passwordsbeforestoringthem.Forinstructionsonchangingthemaster password,refertoChangingtheMasterPasswordonpage 244. 3 Determine a strategy for outbound passwords and the master password. Before youlaunchandconfigureyourIntegrationServerthefirsttime, determinehowyouwanttheIntegrationServertohandletheoutbound passwordsandmasterpasswordwithrespecttowheretheyarestored, howtheyareencrypted,andhowoftentheymustbechanged.Ifyou changethesesettingsaftertheIntegrationServerhasbeenconfigured, themasterpasswordandoutboundpasswordscanbecomeoutofsync. SeeChapter 16,OutboundPasswordsformoreinformation.
398
Stage 2: Basic Configuration

UsetheIntegrationServerAdministratortoconfigurethewayinwhichtheserverwill sendoutboundrequests,acceptinboundrequests,expiresessions,andissueerror messages. Step 1 Action Set up the ports.UsethePortsscreentospecifytheportsonwhichthe serverwilllistenforrequests. Tip! IfyouwillreceiveHTTPand/orHTTPSrequestsonmultipleports, youmaywanttodisableallbutoneport(theoneyouwillusetointeract withtheIntegrationServerAdministrator)untiltheserverisreadyfor production. Forinstructionsonhowtosetupanddisableports,seeSettingUp AliasesforRemoteIntegrationServersonpage 68. 2 Specify the proxy servers. UsetheProxy Servers screentospecifytheproxy server(s)(ifany)throughwhichthisserverwillissueoutboundrequests. SpecifywhichURLs(ifany)canbypasstheproxyserver. Forinstructionsonhowtospecifyproxyserversandbypasslists,see SettingUpAliasesforRemoteIntegrationServersonpage 68. 3 Configure session timeouts. UsetheResourcesscreentosetthetimeout valueyouwanttheservertouse. Forinstructions,seeSettingtheSessionTimeoutLimitonpage 65. 4 Specify the error message recipients and an SMTP server.UsetheLogging screentospecifytheemailaddresswhereyouwanttheservertosend errormessageswhenanexception(acriticalservererrororabinding failure)occursandthenameoftheSMTPservertouseforthispurpose. Forinstructions,seeConfiguringWheretheIntegrationServerWrites Logging,Status,andOtherInformationonpage 78. 5 Set up logging.Forinstructions,seethewebMethodsLoggingGuide.
399
Stage 3: Setting Up Users, Groups, and ACLs

UsetheIntegrationServerAdministratortoidentifyuseraccounts,groups,andaccess controllists(ACLs)toprovideappropriatelevelsofaccesstotheservicesthatwillrunon thisserver. Step 1 Action Identify service security requirements.Servicesareimplicitlyblockedfrom accessbyanyoneotherthanAdministratorsandDevelopers.Determine whatlevelofaccessisrequired,whetherlimitedtoonegroupofusers, allauthenticatedusers,orevenunauthenticatedusers,andapplythe appropriateACLtotheservice. Create user IDs and groups or configure an external directory.Ifyouhave secureservices,identifyusersand/orclientapplicationsthatare authorizedtoaccessthoseservicesandcreategroupsthatcontainthe authorizedmembers. Ifyoursiteusesanexternaldirectory(LDAPorcentraluser management),youcanconfiguretheservertoaccesstheuserandgroup informationfromtheexternaldirectory. ForinstructionsforcreatinguserIDs,seeAddingUserAccountson page 48.Forinstructionforcreatinggroups,seeAddingGroupson page 56.Forinstructionsforusinganexternaldirectory,seeChapter 17, ConfiguringaCentralUserDirectoryorLDAP. 3 Create ACLs.CreatetheACLsneededtomeetyourservicessecurity requirementsandassignthegroupsyouhavecreatedtotheseACLs.For instructions,seeCreatingACLsonpage 173. Identify backup administrators. Selectoneortwouserswhocanactasa backupadministratorwhentheprimaryadministratorisunavailable. UsetheUsers and Groupsscreentoaddtheseuserstothe Administratorsgroup. Forinstructionsonhowtograntauseradministratorprivileges,see SettingUpAdministratorsonpage 141.
400
Stage 4: Publishing Packages

Installandconfigurethepackagesthatwillrunonthisserver. Step 1 Action Install services on the server.Useoneofthefollowingmethodstopublish yourservicestotheproductionserver: Method 1.UsethePackages > Publishingscreentoreplicatethe packagesfromthedevelopmentservertotheproductionserver. Forinstructions,seeCopyingPackagesfromOneServerto Anotheronpage 292. Method 2. UsetheIntegrationServerAdministratorofthepublishing servertocreateazipfilecontainingeachpackageyouwantto publish;then: 1 2 3 Copythezipfiletofollowingdirectoryonthetargetserver: IntegrationServer_directory\replicate\inbound UsethePackages > Managementscreentoinstalleachpackage. Configure the services on the server.Ensurethateachserviceisenabled. Then,configurethefollowingoperatingparametersforeach: ACLassignment Forinstructions,seeAssigningACLstoFolders,Services,and OtherElementsonpage 176. Cachingparameters Forinstructions,seethewebMethodsDeveloperUsersGuide. OutputTemplateAssignment Forinstructions,seethewebMethodsDeveloperUsersGuideand DynamicServerPagesandOutputTemplatesDevelopersGuide. XMLbinding Forinstructions,seethewebMethodsDeveloperUsersGuideandXML ServicesDevelopersGuide.
401
Stage 5: Installing Run-Time Classes

IfyourservicesuseruntimeclassesbeyondthoseprovidedbyJavaortheIntegration Server(e.g.,CORBAorMQSeriesclasses),installthoseclassesontheserver. Step 1 Action Install run-time classes.Obtaintheziporjarfilefromthevendor,andthen copytheziporjarfiletoadeviceordirectorythatyourIntegration Servercanaccess. Update the classpath. Updatetheclasspathstatementintheserver.shor server.batfilesothatitpointstothedirectoryinwhichyouhave installedtheruntimeclasses.
Stage 6: Preparing Clients for Communication with the Server

Ifyouhaveapplications(forexample,JavaorVisualBasicorC/C++programs)thatyou wanttobeIntegrationServerclients,youmustpreparetheclientsforcommunication withIntegrationServer. Step 1 Action TheIntegrationServerclient.jarfilecontainsclassesthatclientsneedto communicatewithIntegrationServer.Ifyouhaveclientsonthesame machineasIntegrationServerorDeveloper,settheclasspathonthe machinetoincludetheclient.jarfile.Theclient.jarfileislocatedinthe \libdirectory,sosettheclasspathto%CLASSPATH%;Integration Server_directory\lib\client.jaror %CLASSPATH%;Developer_directory\lib\client.jar,asappropriate. IfyouhaveclientsonmachinesthatdonotalsohosteitherIntegration ServerorDeveloper,dothefollowingforeachmachine: 1 NavigatetotheIntegrationServer_directory\libor Developer_directory\libdirectoryandcopytheclient.jarfiletoany directoryontheclientmachine. IfyouwanttheclienttouseSSLtocommunicatewithIntegration Server,navigatetotheIntegrationServer_directory\lib\entrustor Developer_directory\lib\entrustdirectoryandcopytheenttoolkit.jar filetoanydirectoryontheclientmachine. Settheclasspathontheclientmachinetoincludetheclient.jarfile and,ifapplicable,theenttoolkit.jarfile.Forexample,ifyouputthe client.jarfileandtheenttoolkit.jarfileinthec:\myappdirectory,you wouldsettheclasspathto %CLASSPATH%;c:\myapp\client.jar;c:\myapp\enttoolkit.jar.
402
Stage 7: Setting Up Security

Takethefollowingstepstoensurethatthesecuritymeasuresyouwanttousearein place. Step 1 Action Check passwords. VerifythatthepasswordsfortheAdministratorand Replicatoraccountsandthemasterpasswordforoutboundpassword encryptionhavebeenchangedfromthedefaultvaluesassignedby webMethodsIntegrationServer. Edit the index.html file to prevent access to Integration Server Administrator. If youwanttopreventauserfrominadvertentlyaccessingtheIntegration ServerAdministrator,editthefollowingfile: IntegrationServer_directory\packages\Default\pub\index.html ChangetheSRCinthe<framesrc=/WmRoot/index.dsp>tagtosome innocuouspageyouhavecreated(perhapsonethatdisplaysanerror messagewithalternatelinks). Notethatifyouimplementthissafeguard,youwillnotbeabletoinvoke theIntegrationServerAdministratorinthestandardway(i.e.,simply connectingtotheIntegrationServerslisteningport).Instead,youwill needtotypetheIntegrationServerAdministratorscompleteURLas shownbelow:
http://Server:Port/WmRoot/index.dsp
where: ServeristhenameoftheIntegrationServer,and PortistheportonwhichitlistensforHTTPrequests. 3 4 5 6 Check user accounts. Verifythatalluseraccountshavepasswordsas required. Check ACL assignments.VerifythatallsecureserviceshavecorrectACL assignments. Check proxy server settings.Verifythatproxyserversettingsandbypass listarecorrect. Restrict access. Configureallow/denyliststorestrictinboundrequestsas necessary.
403
Step 7
Action Install and configure digital certificates.IfyouaredeployinganSSLenabled server,installtheserverscert.derandprivkey.derfilesinthefollowing directory: IntegrationServer_directory\config\ Then,usetheCertificatesscreentoconfigureX.509features. ForinformationaboutsettinguptheservertouseSSL,seeChapter 11, SecuringCommunicationswiththeServer.
Configure HTTP routing systems.Ifyourserversitsbehindarouting,load balancing,orURLfilteringsystem,consultwiththeadministratorof thatsystemtoensurethatitwillpassinboundrequeststothe IntegrationServer. Ensure security of operating system.ThesecurityofyourIntegrationServer dependsonthesecurityofyouroperatingsystem.Therefore,makesure youroperatingsystemisproperlyconfigured,thatallsecuritypatches havebeenapplied,andthatunnecessarynetworkservices,suchastelnet ormail,havebeenremoved.
Stage 8: Startup and Test

Starttheserverandtestservicestoensurethattheyoperateasexpected. Step 1 Action Verify that ports are enabled. Ifyoudisabledtheportstopreventaccessto theserverduringthesetupphase,usethePortsscreentoenablethem now. Tip! Afteryouenableaport,pingittoverifythatitisoperational. 2 Restart the server.UsetheIntegrationServerAdministratortorestartthe servertoensureallsettingsthatyouhavemadeareineffect. Forinstructions,seeRestartingtheIntegrationServeronpage 38. 3 Test services. Performteststoensurethatuser/clientapplicationscan accesstheserversuccessfully. Note: Duringthistestyoumayalsowanttoverifythatyourcurrent licensewillaccommodatetheexpectedconcurrencydemandsonthis server.ContactSoftware AGtoincreasenumberoflicensedsessionsif necessary. 4 Go Live!
404
Stage 9: Archive Sources

Archiveamastercopyofthepackagesontheserverandthesourcefilesthatwereusedto buildthem. Step 1 2 Action Copythecontentsoftheserver\packagesdirectorytoanotherdevicefor backupandarchivalpurposes. Archiveacopyofallthesourcefilesthatwentintoproducingthe servicesdeployedonthisserver.
405
406
Server Configuration Parameters

408 408 408 409 410 411 416 418 444 445
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . watt.config. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . watt.core. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . watt.debug. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . watt.debug2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . watt.net. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . watt.security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . watt.server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . watt.tx. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . watt.xslt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
407
B Server Configuration Parameters
Introduction
Thisappendixcontainsadescriptionoftheparametersyoucanspecifyintheserver configurationfile(server.cnf),whichislocatedintheIntegrationServer_directory\config directory.TypicallyyouwillusetheSettings > Extended screenfromtheIntegrationServer Administratortoupdatethisfile,buttheremightbetimeswhenyouneedtoeditthefile directlyusingatexteditor.Ifyoueditthefiledirectly,youshouldfirstshutdownthe IntegrationServerbeforeupdatingthefile.Afteryoumakethechanges,restartthe server. Theserverusesdefaultvaluesformanyoftheparameters.Ifaparameterhasadefault,it islistedwiththedescriptionoftheparameter.Manyoftheseparametersaresetasyou administerthewebMethodsIntegrationServerusingtheIntegrationServer Administrator.
watt.config.
watt.config.systemProperties Specifiesthelistofadditionalsystemparameterswhosenamedoesnotstartwithwatt. Eachadditionalsystempropertyisseparatedbyacomma.Bydefault,theproperty mail.imap.partialfetch isincludedasanadditionalsystempropertywithadefault valuesettotrue.
watt.core.
watt.core.schema.generateSubstitutionGroups WhengeneratinganISdocumenttypefromanXMLSchemadefinitionthatcontainsa substitutiongroup,indicateswhethertheresultingdocumenttypecontainsanoptional elementforeachmemberofasubstitutiongroup.Whenthispropertyissettofalse,the resultingdocumenttypecontainsafieldthatcorrespondstotheheadelementinthe substitutiongroup,butdoesnotcontainanyelementsformembersofthesubstitution group.Whenthispropertyissettotrue,theresultingdocumenttypecontainsafieldthat correspondstotheheadelementandfieldsthatcorrespondtoeachmemberelementof thesubstitutiongroup.Allthefields,includingtheheadelement,aremarkedasoptional elements.Thedefaultisfalse. watt.core.validation.multipleroot Specifieswhetherthepub.schema:validateserviceistovalidatemultiplerootswhen processingmultipartdocuments.Whenthewatt.core.validation.multipleroot propertyissettotrue,thepub.schema:validateservicechecksformultiplerootnodes.If multiplerootnodesarefound,theserviceflagsavalidationerror.Whenthe watt.core.validation.multiplerootpropertyissettofalse,thepub.schema:validate servicedoesnotperformmultiplerootvalidations.Thedefaultistrue.
408
watt.debug.
watt.debug.layout SpecifiestheformatofmessageswrittentotheserverslogfileandtotheLogs > Server screen.Youcanspecifyoneofthefollowingformats:
new
Messageswillbeinthefollowingformat: (Component)[ComponentID.00SubComponentID.SubComponentID.MessageKey] TimeStampMessageTypeMessageText (IS.SERVER)[ISS.0025.25.6]2007073110:45:27EDTINFO:LicenseManagerstarted

legacy
ThisformatcorrespondstothemessageformatusedinIntegrationServerpriorto version7.1.Usethisformatifyouneedtomaintainbackwardcompatibilitywiththe previousmessageformat.Forexample,youmighthavewrittencodetoprocess messageswrittentotheserverlog. Whenyouselectlegacyasthemessagelayout,messageswillappearinthefollowing format: TimeStamp[ComponentID.00SubComponentID.MessageKeyMessageType]MessageText 2007073110:39:59EDT[ISS.0025.0006I]LicenseManagerstarted Thisisthedefault. watt.debug.level SetslevelofdebugginginformationwrittentotheserverslogfileandtheLogs > Server screen.ThedefaultisInfo. Specify... Off Fatal Error Warn Info Debug Trace To display... Nomessages. Fatalmessagesonly. Errorandfatalmessages. Warning,error,andfatalmessages. Informational,warning,error,andfatalmessages.Thisisthe default. Debug,informational,warning,error,andfatalmessages. Trace,debug,informational,warning,error,andfatalmessages.
Note: Youcanalsosetthevalueofthewatt.debug.levelpropertybysettingthelogging levelfortheDefaultfacilityontheSettings > Loggingscreen.Formoreinformation aboutconfiguringlogging,seethewebMethodsLoggingGuide.
409
PriortoIntegrationServer7.1,IntegrationServerusedanumberbasedsystemtosetthe levelofdebuginformationwrittentotheserverlog.IntegrationServermaintains backwardcompatibilitywiththissystem.Thetablebelowdescribesthenumberbased system. Specify... 0 1 2 3, 4 5, 6, 7 8, 9, 10 To record... Criticalmessagesonly. Errorandcriticalmessages. Warning,error,andcriticalmessages. Informational,warning,error,andcriticalmessages. Debug,informational,warning,error,andcriticalmessages.Thisisthe default. Trace,debug,informational,warning,error,andcriticalmessages. Theserverrecordsmorelevelsofinformationalmessagesthehigheryouset thenumber. watt.debug.logfile Ifstoringloggingserver,session,service,anderrordatainflatfiles,specifiesthefully qualifiedpathtothedirectorythatcontainsthefiles.ThedefaultistheIntegration Server_directory\logsdirectory.Forcompleteinformation,seethewebMethodsLogging Guide.
watt.debug2.
watt.debug2.facList Specifiesacommadelimitedlistofenabledfacilitiesforwhichtheserverlogs information.Thefacilitiesarenumbered.Thedefaultis999,whichindicatestheserveris tologinformationforallfacilities.Specify1000toprohibittheserverfromlogging informationforanyservice. Toviewthenamesoffacilities,usetheLog SettingsscreenoftheIntegrationServer Administratortoenableanddisablefacilitiesforwhichyouwanttheservertolog information watt.debug2.logstringfile Specifiesthename(withouttheextension.txt)forthedictionaryfilethatcontainserror codesandfacilities.Thedefaultis lib\logstr (EnglishVersion).
410
watt.net.
watt.net.email.validateHost ControlswhethertheIntegrationServerenforcesIPaccessrestrictionsforemaillisteners. Whendefininganemailport,youcandefineIPaccessrestrictionsthatspecifythehosts thatareallowedordeniedaccessviatheemailport.Setthispropertytotrueifyouwant servertoenforcetheIPaccessrestrictionsforemaillistenersorfalseifyoudonot.The defaultistrue. watt.net.ftp.ignoreErrors Specifies,usingacommaseparatedlist,anyFTPcommanderrorcodesthatyouwantthe FTPclienttoignore.Forexample,settingthepropertyto501,505causestheFTPclient toignoreerrorcodes501and505. watt.net.ftpClientTimeout Specifiesthelengthoftime,measuredinseconds,anFTPsessioncanbeidlebeforeitis removedfrommemory.Thedefaultis600seconds(10minutes). Note: YoucansetadifferentidletimeoutforanindividualFTPoperationusingthe clientTimeoutinputparameterforthepub.client:ftporpub.client.ftp:loginservices.Formore informationabouttheseservices,seethewebMethodsIntegrationServerBuiltInServices Reference. watt.net.ftpClientDataConnTimeout SpecifiesthenumberofmillisecondsthatanFTPserviceexecutinginactivemodewaits foraremoteFTPservertoconnecttoit.Iftheconnectionisnotestablishedinthe specifiedamountoftime,anexceptionisthrown.Thedefaultvalueis30000milliseconds (30seconds). watt.net.ftpConnTimeout SpecifiesthemaximumnumberofmillisecondstheFTPlistenerallowstheconnection withtheclienttoremaininactive.Thedefaultis15minutes. watt.net.ftpDataConnTimeout SpecifiesthemaximumnumberofmillisecondstheFTPlistenerwaitsbetweensuccessive readswhenperformingafileupload.Thedefaultis60000milliseconds(60seconds). watt.net.ftpPassiveLocalAddr SpecifiestheaddressthatshouldbesentbythePORTcommand.AhostnameorIP addresscanbespecified. Whenrunninginpassivemode,theFTPportsendsaPORTcommandtotheFTPclient. ThePORTcommandspecifiestheaddressandporttowhichtheclientshouldconnectto createadataconnection.IftheFTPportisbehindaNATserver,however,theaddressof thehostonwhichtheIntegrationServerrunsisnotvisibletotheFTPclient. ConsequentlythePORTcommanddoesnotcontaintheinformationtheclientneedsto connecttotheserver.Toremedythissituation,youcanspecifyavalueforthe watt.net.ftpPassiveLocalAddrproperty. Alternatively,whenyouconfigureanFTPport(seeAddinganFTPPortonpage 101), youcanusethePassive Mode Listen Addressfieldtospecifythepassivemodeaddressfor
411
anindividualFTPport.Thatway,youcanspecifyadifferentpassivemodeaddressfor eachFTPport.IfanaddressisspecifiedinthePassive Mode Listen Addressfieldandinthe watt.net.ftpPassiveLocalAddrproperty,thePORTcommandusesthevaluespecifiedin thewatt.net.ftpPassiveLocalAddrproperty. watt.net.ftpPassivePort.min SpecifiestheminimumportnumberofaportrangeforFTP/FTPSlistenerstousewitha clientdataconnectionthatusespassivetransfermode(PASV).Mustbeusedwith watt.ftpPassivePort.max.Whenaportrangeisspecifiedwiththeseproperties,onlythe portswithinthespecifiedminimumandmaximumportrange(inclusive)areusedasthe listeningportsforincomingFTP/FTPSclientdataconnections.Thisenablesafirewall administratortoopenonlythespecifiedports. Operationalconsiderations: Ifbothpropertiesarenotpresentorundefined,FTP/FTPSlistenerscontinuethe previousbehavioroflisteningonanyfreeport. Ifthevaluespecifiedforwatt.net.ftpPassivePort.minislessthan1,adefaultvalueof1 isused.Ifthevaluespecifiedforwatt.net.ftpPassivePort.maxisgreaterthan65534,a defaultvalueof65534isused.Whenbothoftheseconditionsexistsimultaneously, FTP/FTPSlistenerscontinuethepreviousbehavioroflisteningonanyfreeport. AnerrormessageisreturnedtotheFTP/FTPSclientonthecommandchannelwhen thespecifiedvaluesdonotfallwithintheexpectedrange.Forexample,ifoneofthe propertiesisnotdefined,ifthewatt.net.ftpPassivePort.minvalueislargerthanthe watt.net.ftpPassivePort.maxvalue,orifoneofthepropertiesisnotavalidnumber. Anerrormessageisalsoreturnedwhenalltheportsinthespecifiedportrangearein use. SpecificdetailsoftheerrormessagesareavailableintheserverYYYYMMDD.logfile. RestartingtheIntegrationServerisnotrequiredafterdefiningthesesettings.Youcan modifytheportrangepropertiesintheIntegrationServerAdministratoratanytime. watt.net.ftpPassivePort.max SpecifiesthemaximumportnumberofaportrangeforFTP/FTPSlistenerstousewitha clientdataconnectionthatusespassivetransfermode(PASV).Mustbeusedwith watt.ftpPassivePort.min.Forusageinformation,seewatt.ftpPassivePort.min. watt.net.ftpSweepInterval Specifiesthefrequency,measuredinseconds,atwhichanFTPsweeperexecutes.TheFTP sweeperiteratesthroughtheFTPsessionsinmemoryandremovesthesessionsthathave exceededtheirallottedidletimeout.Bydefault,theFTPsweeperexecutesevery600 seconds(10minutes). watt.net.ftpUseCertMap SpecifieswhethertheIntegrationServerwillhonorcertificatemapsforrequestsreceived byFTPSports. Whenthispropertyissettofalse(thedefault),theIntegrationServerignorestheuser specifiedonaclientcertificateandlogstheuserinwiththeinformationprovidedonthe userid/passwordpromptinstead.
412
Whenthispropertyissettotrue,iftheclientcertificatehasbeenpreviouslymappedto anIntegrationServeruser,theIntegrationServerwilllogtheuserinastheuserid specifiedintheclientcertificate.TheIntegrationServerignorestheuseridprovidedon theuserid/passwordprompt. Forexample,supposewatt.net.ftpUseCertMapissettofalse,andacertificatehasbeen previouslymappedtouserAlice.WhenauserprovidesacertificateforuserAliceand entersAlicesusernameandpasswordinresponsetotheprompt,theIntegrationServer willlogtheuserinasAlice.However,iftheuserprovidesthesamecertificate,but providesBobsusernameandpasswordinresponsetotheprompt,theIntegration ServerwilllogtheuserinasBob.Inotherwords,theIntegrationServerignoresthe certificatemap. Note: TheNone,Request Certificate,andRequire Certificateclientauthenticationsettings ontheFTPSListenerConfigurationscreencontrolwhethertheIntegrationServer asksforacertificateandhowtheIntegrationServerbehaveswhenitdoesnotreceive one.Thewatt.net.ftpUseCertMappropertycontrolshowtheIntegrationServer behaveswhenitdoesreceiveacertificatefromanFTPclient.Formoreinformation aboutclientauthenticationatFTPSandHTTPSports,seeClientCertificateson page 182.Formoreinformationaboutcertificatemapping,seeImportingaClient CertificateandMappingIttoaUseronpage 186. watt.net.httpChunkSize SetsthedefaultchunksizewhensendingaHTTPrequestorresponseusingTransfer Encoding:Chunked.Thedefaultchunksizeis8192bytes. watt.net.maxClientKeepaliveConns Setsthedefaultnumberofclientkeepaliveconnectionstoretainforagiventarget endpoint.If not specified, five keep alive connections are retained. watt.net.maxRedirects SpecifiesthemaximumnumberofHTTPredirectstoallowbeforethrowinganI/O exception.Thedefaultis5. watt.net.proxyHost SpecifiesthehostthatthisservershoulduseforoutboundHTTPrequests.Thereisno default. watt.net.proxyPass SpecifiesthepasswordtouseforauthenticationwiththeHTTPproxyhost.Thereisno default. watt.net.proxyPort SpecifiestheportnumberontheproxyhosttouseforoutboundHTTPrequests.Thereis nodefault. watt.net.proxySkipList SpecifiesalistofdomainnamesforwhichtheIntegrationServershouldnotuseproxy servers.Thedefaultislocalhost.
413
watt.net.proxyUser SpecifiestheusernametouseforauthenticationwiththeHTTPproxyhost.Thereisno default. watt.net.retries Specifiesthenumberoftimestoretryaserverthattimesout.Thiscanbeoverriddenby theclient.Thedefaultis0. watt.net.secureProxyHost SpecifiesthehostthatthisservershoulduseforoutboundHTTPSrequests.Thereisno default. watt.net.secureProxyPass SpecifiesthepasswordtouseforauthenticationwiththeHTTPSproxyhost.Thereisno default. watt.net.secureProxyPort SpecifiestheportnumberontheproxyhosttouseforoutboundHTTPSrequests.There isnodefault. watt.net.secureProxyUser SpecifiestheusernametouseforauthenticationwiththeHTTPSproxyhost.Thereisno default. watt.net.ssl.client.hostnameverification WhenIntegrationServerisactingasanHTTPSclient,thisparameterspecifieswhether IntegrationServershouldrestrictoutboundHTTPSconnectionsonlywhenavalid hostnameisfoundintheserverscertificate. Whensettotrue,IntegrationSerververifiesifthehostnameispresentintheservers certificate.Ifthisverificationfails,anerrorisloggedandtheconnectionisaborted. Whensettofalse,IntegrationServerwillbypassthehostnameverification.The defaultissettofalse. Whensettolog,IntegrationServerlogsthedebugmessageintheserverlogifthe hostnameverificationfails,butallowstheconnectiontogothrough.Ifthehostname verificationsucceeds,nologisgenerated. Thedefaultisfalse. watt.net.ssl.client.strongcipheronly SpecifieswhethertheIntegrationServeristorestrictoutboundHTTPSconnectionstouse strongciphersuitesonly(128bitsessionkeysorhigher).Ifyouspecifyfalse(the default),whentheIntegrationServerinitiatesaconnectiontoanotherserver,itwill attempttonegotiateastrongciphersuite,andifunsuccessfulwillfallbacktousinga weak(64,56,or40bit)ciphersuite.Ifyouspecifytrue,whentheIntegrationServer initiatesaconnectiontoanotherserver,itwillattempttonegotiateastrongciphersuite, andifunsuccessfulwilldisconnectratherthanuseaweakciphersuite. watt.net.ssl.server.clientHandshakeTimeout Specifiesthenumberofmillisecondstheserverwaitsforaresponsefromtheclient duringanSSLhandshakebeforetimingout.Thedefaultis20000milliseconds.
414
watt.net.ssl.server.strongcipheronly SpecifieswhethertheIntegrationServeristorestrictinboundHTTPSconnectionstouse strongciphersuitesonly(128bitsessionkeysorhigher).Ifyouspecifyfalse(the default),whenaclientconnectstotheIntegrationServer,theserverwillattemptto negotiateastrongciphersuite,andifunsuccessfulwillfallbacktousingaweak(64,56, or40bit)ciphersuite.Ifyouspecifytrue,whenaclientconnectstotheIntegration Server,theserverwillattempttonegotiateastrongciphersuite,andifunsuccessfulwill disconnectratherthanuseaweakciphersuite. watt.net.timeout SpecifiesthenumberofsecondstheserverwaitsforanHTTPrequesttobefulfilled beforetherequesttimesout.Thedefaultis0. watt.net.useCookies Accept(true)ordeny(falseornull)cookieswhencommunicatingwithWebservers.Itis almostneveragoodideatoturnthisoff.Defaultstotrue. watt.net.userAgent SpecifiesthevaluetheserverusesintheHTTPUserAgentrequestheaderwhenit requestsaWebdocumentfromaWebserver.ThedefaultisMozilla/4.0 [en] (WinNT; I). watt.net.webapp.cookies.useRelevantPath SpecifieshowWmTomcatcancreatefewercookiestopreventthewebapplicationfrom loggingoutbecauseofexceedingthebrowsercookielimit. Whenthispropertyissettotrue,WmTomcatreturnscookiesthatcontaintheURIprefix inthepathname,andmorecookiesarecreated.Bydefault,WmTomcatreturnscookies thatcontainaURIprefixinthepathname.Asaresult,WmTomcatcreatesaseparate cookieforeachuniquepath.Forapplicationsthatincludepagesacrossmanydifferent paths,theresultcanbemanycookies.Iftheapplicationexceedsthecookielimitofthe browserthatinvokedit,theapplicationisforcedtologout. Butwhenthispropertyissettofalse(thedefault),WmTomcatdoesnotincludetheURI prefixinthecookie,andfewercookiesarecreated. Forexample,whenwatt.net.webapp.cookies.useRelevantPathissettofalse,andyou visittheWmTomcatsitessite/a.jsp -> site/bar/b.jsp -> site/bar/baz/c.jsp, WmTomcatcreatesjustonecookie:cookie1)name=ssnid,path=/. Butwhenthispropertyissettotrue,WmTomcatcreatesthefollowingcookies: cookie1)name=ssnid,path=/site/ cookie2)name=ssnid,path=/site/bar/ cookie3)name=ssnid,path=/site/bar/baz Thedefaultisfalse.
415
watt.security.
watt.security.caCert SpecifiesthepathandfilenameofthefilecontainingthecertificateoftheCertificate Authority(CA)thatissuedtheIntegrationServersdigitalcertificate.Thedefaultis config\cacert.der. watt.security.CADir Specifiesthepathnameofadirectory(relativetotheserverhome)thatcontainsthe digitalcertificatesofCAsthatyourIntegrationServertrusts,forexampleconfig\cas. Whenyouindicatethatyouwanttheservertorequestclientcertificates (watt.server.requestCerts),theserverautomaticallypresentsthelistofcertificatesin thisdirectorytotheclientwhenitsubmitsitsowncertificate.Thereisnodefault. watt.security.cert.wmChainVerifier.trustByDefault Incaseswherenodirectoryoradirectorycontainingnocertificatesisspecifiedforthe TrustedCertificatesdirectory,specifieswhethertheserveristotrust: Certificatespresentedbypeerservers(inresponsetothisserversoutboundrequest) S/MIMEsignatures Specifieswhethertheserveristotrust(true)ornottrust(false)certificatesandS/MIME signaturesinthissituation.Thedefaultistrue.Forimprovedsecurity,Software AG recommendsthatyousetthisparametertofalseandspecifyaTrustedCertificates directory. watt.security.fips.mode SpecifieswhethertheserveristosupportFIPS(FederalInformationProcessing Standards).Thedefaultisfalse.Ifthisparameterissettotrue,theserverinitializesFIPS aspartofserverstartup.IfFIPSinitializationfails,theerrorisloggedtoserver.logand theservershutsdown. watt.security.ope.AllowInternalPasswordAccess SpecifieswhetherthebuiltinservicessupportingOPE(outboundpasswordencryption) forflowservicesmayaccesstheIntegrationServersinternalpasswords.Ifthisparameter issettotrue,theOPEservicesmayaccesstheinternalpasswords.Ifitissettofalse,the OPEservicesarenotallowedaccesstotheinternalpasswords.Bydefault,thisparameter issettofalse. InternalpasswordsarepasswordsforusebytheIntegrationServeritselftoaccesssecure resources(e.g.,remoteIntegrationServers,JDBCconnectionpools,LDAPservers,etc.). InternalpasswordsaremanagedusingtheIntegrationServerAdministratorandare storedintheoutboundpasswordstore.Flowservicesarealsoallowedtostorepasswords intheoutboundpasswordstore.However,bydefault,passwordsstoredbyaflowservice areconsideredpublic,asopposedtointernal.Thisdistinctionallowsflowservicesto usetheoutboundpasswordstoreasasecuremechanismforstoringandretrieving passwords,butprotectstheIntegrationServersinternalpasswords.
416
Youcanallowflowservicestoaccessinternalpasswords(i.e.,store,retrieve,andmodify) bysettingwatt.security.ope.AllowInternalPasswordAccesstotrue.However,thisshould bedoneonlyifyouexplicitlywishtohaveaflowserviceworkwithinternalpasswords. Otherwise,itisrecommendedyoudenyaccesstointernalpasswordsbysetting watt.security.ope.AllowInternalPasswordAccesstofalse. watt.security.pki.jnditimeout Specifieshowlong(inmilliseconds)theIntegrationServerattemptstoconnecttothe LDAPdirectorywhenexecutingservicesinthepub.pki.smimefolder.Thedefaultis20000 milliseconds(i.e.,20seconds). watt.security.privateKey Specifiesthepathandfilenameofthefilethatcontainstheprivatekeyassociatedwith theIntegrationServersdigitalcertificate.Thedefaultisconfig\privkey.der. watt.security.ssl.cacheClientSessions ControlswhethertheserverreusespreviousSSLsessioninformation(e.g.,client certificates)forconnectionstothesameclient.Ifyouhaveastableenvironmentwhere repeatedauthenticationsfromthesameclientproducethesameresult,setthisproperty totrue.Whenthispropertyissettotrue,theservercachesandreusesSSLsession information.Ifyourenvironmentisnotstable(e.g.,clientcertificateschangefrequently), setthispropertytofalse.Notethatsettingthepropertytofalsewilldecrease performance.Thedefaultistrue. watt.security.signedCert SpecifiesthepathandfilenameofthefilecontainingtheIntegrationServersdigital certificate.Thedefaultisconfig\cert.der. watt.security.ssl.ignoreExpiredChains SpecifieswhethertheIntegrationServerignoresexpiredCAcertificatesinacertificate chainitreceivesfromanInternetresource(i.e.,aWebserver,anotherIntegrationServer). TohavetheIntegrationServerignoreexpiredCAcertificatesandallowSSLconnections whenacertificateisexpired,setthewatt.security.ssl.ignoreExpiredChainssettingto true. Notethatthisislesssecurethandenyingconnectionswhenacertificateisexpired. Thedefaultisfalse.Formoreinformationaboutthissetting,seeWhentheIntegration ServerIsanSSLServeronpage 146. watt.security.ssl.keypurposeverification WhenIntegrationServerisactingasanHTTPSclient,thisparameterspecifieswhether theservershouldrestrictoutboundHTTPSconnectionsonlywhenavalidExtendedKey Purposefieldispresentintheserverscertificate.ThecontentoftheKeyPurposefield, id-kp-serverAuth,shouldbeintheIETFmandatedformat,TLS WWW server authenticationfortheverificationtopass.RefertothesectiontitledExtendedKey Usage,inthedocumenthttp://www.ietf.org/rfc/rfc3280.txtformoreinformation regardingthisformat. Threevaluesareallowedforthiswattpropertytrue,falseandlog. Whensettotrue,itwillverifythepresenceofthekeypurposefieldintheservers certificate.Ifthekeypurposeverificationfails,anerrorisloggedandtheconnection isaborted.Iftheverificationsucceeds,noerrorislogged.
417
Whensettofalse,itwillbypasstheverificationofthekeypurposefield.Thedefault isfalse. Whensettolog,itwilllogadebugmessageintheserverlogifthekeypurposefield verificationfails. Thedefaultisfalse.
watt.server.
watt.server Thisisaninternalparameter.Donotmodify. watt.server.allowDirective Restrictstheuseofspecifieddirectivestospecifiedports.Forinformationondirectives, seeControllingtheUseofDirectivesonpage 167).Thesyntaxforthispropertyis:
watt.server.allowDirective=directive1,port-string,directive2,port-string
portstringisacommadelimitedlistofportnumberssuchas5555,6666. Supposeyouwanttoallowallportstousethedefaultdirective,butyouwantonlythe portslistedbelowtousetheotherdirectives: restrictuseoftheinvokedirectivetoports5555and7777 restrictuseofthewebdirectivetoports6666and7777 restrictuseoftheSOAPdirectivetoport7777 Youwouldspecifythefollowing:

watt.server.allowDirective=invoke,5555,7777,web,6666,7777,soap,7777
watt.server.auditDBSize Ifmaintainingthetemporarystoreondisk,specifiesthespaceallocation,inmegabytes, forthetemporarystorefiles.Thedefaultis10.Forcompleteinformation,seethe webMethodsLoggingGuide. watt.server.auditDir Ifyouaremaintainingthetemporarystoreforloggingdataondisk,specifiesthefully qualifiedpathtothedirectorythatcontainsthetemporarystorefile.Thedefaultisthe IntegrationServer_directory\auditdirectory.Forcompleteinformation,seethewebMethods LoggingGuide. watt.server.auditDocIdField SpecifiesacustomdocumentIDvaluetoidentifydocumentsinastandardwayandto provideuniformbusinesscontextintheloggingdisplay.Somedocumentsareloggedby webMethodsBrokerthroughWmLogUtiltothedocumentdatabase,andsomeare loggedbyvariouscomponentswithintheIntegrationServer,forexample,ifaservice fails,orifthenumberofretriesinatriggerareexceeded.Asaresult,whenviewingthe DocumentMonitor,somedocumentsareloggedwithanumericdocumentID,andsome areloggedwithlengthyhexadecimalstringsasthedocumentID.Thecustomdocument IDvaluethatyouspecificwillbeusedtocreatethedocumentloggingID.Thisvalueis usedinplaceoftheBrokerEvent.getEventId()value(theoriginaldocumentIDbehavior).
418
ThevaluemustbeintheformofaBrokerunicodestring,andvaluesinexcessof128 characterswillbetruncated.Ifthisextendedsettingismissing,theoriginaldocumentID behaviorapplies.Ifthisextendedsettingispresentbutundefined(null),the_env.uuid valueisusedifpresent;ifno_env.uuidvalueisdefined,theoriginaldocumentID behaviorapplies.Formoreinformationaboutdocumentlogging,seethewebMethods BrokerAdministratorsGuide. watt.server.auditFetchSize Specifiesthenumberoflogentriesforeachloggingthreadtopullfromthetemporary storeandstore,asabatch,inflatfilesordatabase.Thedefaultis10.Forcomplete information,seethewebMethodsLoggingGuide. watt.server.auditGuaranteed Specifieswhethertomaintainthetemporarystoreforloggingdataondiskorinmemory. Thedefaultistrue(disk).Forcompleteinformation,seewebMethodsLoggingGuide. watt.server.auditLog Specifieswhethertogloballyenableordisableservicelogging.ThedefaultisperSvc (enablecustomizedloggingonaservicebyservicebasis).Forcompleteinformation,see thewebMethodsLoggingGuide. watt.server.auditLog.error Specifieswhethertogloballyenableordisableerrorlogging.Thedefaultistrue(enable). Forcompleteinformation,seethewebMethodsLoggingGuide. watt.server.auditLog.gd Specifieswhethertogloballyenableordisableguaranteeddeliverylogging.Thedefault istrue(enable).Forcompleteinformation,seethewebMethodsLoggingGuide. watt.server.auditLog.security Specifieswhethertogloballyenableordisablesecurityauditing.Thispropertywillbe updatedautomaticallywhentheuserenablesordisablessecurityauditingonIntegration ServerAdministrator.Thedefaultisfalse.Formoreinformationaboutsecurityauditing, seethewebMethodsLoggingGuide. watt.server.auditLog.session Specifieswhethertogloballyenableordisablesessionlogging.Thedefaultistrue (enable).Forcompleteinformation,seethewebMethodsLoggingGuide. watt.server.auditMaxPool Specifiesthemaximumnumberofthreadstouseconcurrentlytowriteloggingdatato thetemporarystore.Thispropertyalsospecifiesthemaximumnumberofthreadstouse concurrentlytopullloggingdatafromthetemporarystoreandwriteittoflatfilesor database.Thedefaultis10.Forcompleteinformation,seethewebMethodsLoggingGuide. watt.server.auditMinPool Specifiestheminimumnumberofthreadstouseconcurrentlytowriteloggingdatatothe temporarystore.Thispropertyalsospecifiestheminimumnumberofthreadstouse concurrentlytopullloggingdatafromthetemporarystoreandwriteittoflatfilesor database.Thedefaultis1.Forcompleteinformation,seethewebMethodsLoggingGuide.
419
watt.server.auditRetryCount Ifstoringloggingdatainadatabase,specifiesthemaximumnumberoftimestoretry writingalogentrytothedatabase.Thedefaultis3.Forcompleteinformation,seethe webMethodsLoggingGuide. watt.server.auditSync Bydefault,theIntegrationServerwritesauditdatatotransientstoragebeforewritingit topersistentstorage.Insomehighvolume,multiuserenvironments,thisbehaviorcan slowperformance.ThispropertyspecifieshowtheIntegrationServerwritesaudit information.Whenthisvalueissettofalse(thedefault),theIntegrationServerwrites auditdatafirsttotransientstorage,thentopersistentstorage.Whenthisvalueissetto true,theIntegrationServerwritesauditdatadirectlytopersistentstorage. watt.server.auditThreshold Specifiesthemaximumnumberoflogentriesthetemporarystorecanhold.Thedefaultis 100,000.Forcompleteinformation,seethewebMethodsLoggingGuide. watt.server.broker.producer.multiclient Specifiesthenumberofsessionsforthedefaultclient.ThedefaultclientistheBroker clientthattheIntegrationServerusestopublishdocumentstotheBrokerandtoretrieve documentsdeliveredtothedefaultclient.Whenyousetthisparametertoavaluegreater than1,theIntegrationServercreatesanewmultisession,sharedstateBrokerclient namedclientPrefix_DefaultClient_MultiPub,touseforpublishingdocumentstothe Broker.Usingapublishingclientwithmultiplesessionscanleadtoincreased performancebecauseitallowsmultiplethreadstopublishdocumentsconcurrently.The defaultis1session. watt.server.broker.replyConsumer.fetchSize SpecifiesthenumberofreplydocumentsthattheIntegrationServerretrievesfromthe Brokeratonetime.IncreasingthereplydocumentstheIntegrationServerretrievesfor eachcallcanreducethenumberofcallstheIntegrationServermakestotheBroker.The IntegrationServermaintainsallreplydocumentsinmemory.Youcanreducetheamount ofmemoryusedforreplydocumentsbydecreasingthenumberofdocumentsthe IntegrationServerretrievesatonetime.Thedefaultis5documents. watt.server.broker.replyConsumer.multiclient Specifiesthenumberofsessionsfortherequest/replyclient.Therequest/replyclientis theBrokerclientthattheIntegrationServerusestosendrequestdocumentstotheBroker andtoretrievereplydocumentsfromtheBroker.Increasingthenumberofsessionsfor therequest/replyclientcanleadtoimprovedperformancebecauseitallowsmultiple requestsandrepliestobesentandretrievedconcurrently.Thedefaultis1session. watt.server.broker.replyConsumer.sweeperInterval Specifieshowoften(inmilliseconds)theIntegrationServersweepsitsinternalmailboxto removeexpiredrepliestopublishedrequests.Thelengthoftheintervalshouldbalance theamountofmemoryconsumedbyexpiredreplieswithretrievingtherepliesfor waitingrequests.TheIntegrationServerusesonebackgroundthreadtoageandremove expiredrepliesandusesmultiplebackgroundthreadstoretrieverepliesforwaiting requests.Whenthesweeperthreadremovesexpiredreplies,itblocksthethreads attemptingtoretrievereplies.Whenthensweeperintervalistoolow,thefrequent executionofthesweeperthreadcandegradeperformancebecauseotherbackground
420
threadscannotretrieverepliesasoften.Asweeperintervalthatistoohighcancausean increaseinmemoryusagebecauseexpiredrepliesconsumememoryforalongerperiod oftime.Thedefaultis30000milliseconds(30seconds). watt.server.brokerTransport.dur SpecifiesthenumberofsecondsofidletimethattheBrokerwaitsbeforesendingakeep alivemessagetoIntegrationServer.IfIntegrationServerdoesnotrespondwithinthe amountoftimespecifiedbythewatt.server.brokerTransport.maxproperty,theBroker sendsanotherkeepalivemessagetoIntegrationServer.IfIntegrationServercontinuesto beunresponsive,theBrokercontinuessendingkeepalivemessagesuntilitreachesthe retrylimitspecifiedbythewatt.server.brokerTransport.retproperty.IftheIntegration Serverstillhasnotrespondedtothekeepalivemessage,theBrokerexplicitlydisconnects theIntegrationServer.Thewatt.server.brokerTransport.durvaluemustbeaninteger greaterthanorequaltozerobutlessthan2147483647.Thedefaultis60seconds. Formoreinformationaboutusingserverparameterstoconfigurethekeepalivesetting withtheBroker,seeSpecifyingtheKeepAliveModefortheBrokerConnectionon page 134. watt.server.brokerTransport.max SpecifiesthenumberofsecondsthattheBrokerwaitsfortheIntegrationServerto respondtoakeepalivemessage.Thisvaluemustbeanintegerbetween0and 2147483647.Thedefaultis60seconds. Formoreinformationaboutusingserverparameterstoconfigurethekeepalivesetting withtheBroker,seeSpecifyingtheKeepAliveModefortheBrokerConnectionon page 134. watt.server.brokerTransport.ret SpecifiesthenumberoftimestheBrokerresendskeepalivemessagesbefore disconnectinganunresponsiveIntegrationServer.Thisvaluemustbeaninteger between1and2147483647.Thedefaultis3retries. Note: TheBrokerignoresthewatt.server.brokerTransport.retparameterif watt.server.brokerTransport.durorwatt.server.brokerTransport.maxaresetto 2147483647.Formoreinformationaboutusingserverparameterstoconfigurethe keepalivesettingwiththeBroker,seeSpecifyingtheKeepAliveModeforthe BrokerConnectiononpage 134. watt.server.cache.flushMins Specifieshowoften(inminutes)theserversweepsthecachetoremoveexpiredcache entriesandtoprefetchcacheserviceentries.Thedefaultis10minutes. watt.server.cache.gcMins Specifieshowoften(inminutes)theserversweepsthecachetoperformgarbage collection.Thedefaultis60minutes. watt.server.cache.isPersistent Specifieswhetheryouwantservercachetobepersistent(true)ornot(false).Thedefault istrue.
421
watt.server.clientTimeout Specifiestheamountoftime(inminutes)afterwhichanidleusersessiontimesout.The defaultis10. watt.server.cluster.aliasList SpecifiesacommadelimitedlistofaliasesforremoteIntegrationServersinacluster.The IntegrationServerusesthislistwhenexecutingtheremoteinvokesthatupdatetheother clusternodeswithtriggermanagementchanges.Whenthispropertyisconfigured,the Settings > Messaging > Broker/Local Trigger Management > Cluster Viewpagewillbevisibleand theApply Change Across Clustercheckboxwillbeavailablewhenperformingtrigger managementtasks. YoumustbeusingwebMethodsclusteringtousethissetting.Formoreinformation,see thewebMethodsIntegrationServerClusteringGuide. watt.server.cluster.aware Specifieswhetheryouwanttheservertoparticipateinacluster.Thedefaultisfalse. YoumustbeusingwebMethodsIntegrationServerClusteringtousethissetting.For moreinformation,refertothewebMethodsIntegrationServerClusteringGuide. watt.server.cluster.cacheName Specifiesthenameoftheclustertojoin.Anenterprisecanhavemorethanonecluster. Thisvalueallowsthecachingsoftwaretoformseparatecachesforeachcluster.Withouta clustername,allIntegrationServersthatarevisibletooneanotheronthenetworkwould formasinglecache. watt.server.cluster.sessTimeout Specifiesnumberofminutesthattheserverallowsinactivesessionobjectstoremainin theclusterstorebeforeremovingthem.Thedefaultis60. YoumustbeusingwebMethodsIntegrationServerClusteringtousethissetting.For moreinformation,refertothewebMethodsIntegrationServerClusteringGuide. watt.server.compile SpecifiesthecompilercommandtheIntegrationServerusestocompileJavaservicesthat aredevelopedusingtheDeveloper.Thiscompilercommandisalsousedfromthejcode utility.Bydefault,theserverusesjavacclasspath{0}d{1}{2}.Formoreinformation aboutspecifyingthecompilerandJDKtheIntegrationServeristouse,seethe webMethodsInstallationGuide. watt.server.compile.unicode SpecifiesthecompilercommandtheIntegrationServerusestocompileJavaservicesthat arestoredinUnicodeencoding.Thiscompilercommandisalsousedfromthejcode utility.Bydefault,theserverusesjavacencodingUnicodeclasspath{0}d{1}{2}.This settingworkswiththeSunJDKcompiler.Formoreinformationaboutspecifyingthe compilerandJDKtheIntegrationServeristouse,seethewebMethodsInstallationGuide. watt. server. control. controlledDeliverToTriggers. pctMaxThreshold SpecifiesthetriggerqueuethresholdatwhichtheIntegrationServerslowsdownthe deliveryrateoflocallypublisheddocuments.Thisthresholdisexpressedasapercentage ofthetriggerqueuecapacity.Forexample,ifyouspecify80,theIntegrationServer decreasestherateatwhichitdeliverslocallypublisheddocumentstoatriggerqueue
422
whenthattriggerqueuereaches80%capacity.IntegrationServerresumesdelivering documentsatthenormalratewhenthetriggerqueuecapacitydropsbelowthespecified threshold.Thedefaultis90. watt.server.control.maxPersist Specifiesthecapacityoftheoutbounddocumentstore.IntegrationServerplaces publisheddocumentsintheoutbounddocumentstorewhentheconfiguredBrokeris unavailable.Whenthenumberofdocumentsintheoutbounddocumentstoreequalsthe capacity,theIntegrationServerblocksanythreadsexecutingservicesthatpublish documents.TheIntegrationServerresumesexecutionofblockedthreadsaftertheBroker becomesavailable.Thedefaultis500,000documents. watt.server.control.maxPublishOnSuccess Specifiesthemaximumnumberofdocumentsthattheservercanpublishonsuccessat onetime.Forexample,supposethatyousetthemaximumto100documents.ServiceA publishes10documentsonsuccess.ServiceBpublishes90documentsonsuccess.ServiceC publishes5documentsonsuccess.ServiceAandServiceBcanpublishdocuments concurrently.However,ifServiceCbeginstopublishdocumentsbeforeServiceAorServiceB completes,theIntegrationServerthrowsanexceptionforServiceCbecausethedocuments publishedbyServiceCexceedthemaximumnumberofdocumentsthatcanbepublished onsuccessatonetime.IfServiceDpublishes125documentsonsuccessandthemaximum is100,ServiceDwillreceiveanexceptioneverytimeitexecutes.Thedefaultis50,000 documents. watt.server.cron.maxThreads ThemaximumnumberofthreadsthatIntegrationServermaintainsinthecronjobbased schedulerthreadpool.Ifthismaximumnumberisreached,IntegrationServerwaitsuntil processescompleteandreturnthreadstothepoolbeforerunningmoreprocesses.The defaultis5. Note: ThenewscheduleravailablewithIntegrationServer7.1usesthreadsfromthe serverthreadpool.Systemtaskscontinuetousethecronjobbasedschedulerwhich hasitsownthreadpool. watt.server.cron.minThreads Theminimumnumberofthreadsthattheservermaintainsinthecronjobbased schedulerthreadpool.Whentheserverstarts,thethreadpoolinitiallycontainsthis minimumnumberofthreads.Thedefaultis2.Systemtaskscontinuetousethecronjob basedscheduleravailablewitholderversionsofIntegrationServer,whichhasitsown threadpool. Note: ThenewscheduleravailablewithIntegrationServer7.1usesthreadsfromthe serverthreadpool.Systemtaskscontinuetousethecronjobbasedschedulerwhich hasitsownthreadpool. watt.server.dateStampFmt Specifiesthedateformattouseinlogfiles.Youcanuseanyformatthatissupportedby theJavaclassjava.text.SimpleDateFormat.Forexample,todisplaythedatewiththe format08120214:44:33:1235,specifyddMMyyHH:mm:ss:SSSS.
423
watt.server.date.SuppressPatternError Specifieshowtheservershouldrespondifnoinputispassedtothepub.date:dateTimeFormat service.Whensettotrue,theserversimplyreturnsanullvalueforthevalueparameter. Thedefaultisfortheservertothrowanexception. watt.server.db.blocktimeout Note: ThisparameterisforusewiththeWmDBpackageonly.Ifyouareusingthe webMethodsJDBCAdaptertoconnecttoyourdatabases,seethedocumentationfor thatadapterinstead. Thisparameterappliesonlyifyouareusingserverpoolinginsteadofsession pooling,thatis,youhavespecifiedserveronthewatt.server.db.connectionCache property.Seethedescriptionofthatparameter,below,formoreinformation. Specifiesthemaximumtimeinmillisecondstheserveristoblockarequestwhenwaiting foraconnectiontoadatabase.(ThedatabasemustbedefinedbyanaliasintheWmDB package.)Thedefaultistowaitindefinitely.Specifying1alsomeanstowaitindefinitely. Thispropertyisglobaltoallpools. watt.server.db.connectionCache Note: ThisparameterisforusewiththeWmDBpackageonly.Ifyouareusingthe webMethodsJDBCAdaptertoconnecttoyourdatabases,seethedocumentationfor thatadapterinstead. Specifieshowtheservermanagesconnectionstoadatabase. Specifyingservertellstheservertomaintainapoolofconnectionsforeachdatabasethat isdefinedtotheserverthroughanalias.Ifarequestcannotbesatisfiedbecausethepool hasreacheditsmaximumnumberofconnections,theserverblockstherequestandtries againlater. Specifyingsessiontellstheservertocreateadatabaseconnectionpersession.Thatis, whentheserverreceivesaservicerequestthatrequiresadatabaseconnection,itwill createanewconnectionifonedoesntalreadyexistforthatsession;otherwisetheserver willusetheconnectionthatwaspreviouslycreatedforthatsession.Iftheattemptto createaconnectionforthesessionfails,forexamplebecausethedatabasehasno availableslotsforconnections,therequestfails.Thedefaultissession. Althoughenablingdatabaseconnectionpoolingcreatesapoolforeachdatabasedefined toyourserver,youcancontrolthecharacteristicsofeachpoolindividuallybyusingthe Edit Alias InformationscreenoftheIntegrationServerAdministrator.SeeWmDBUsers Guideformoreinformationaboutconfiguringtheservertoconnecttoadatabase.
424
watt.server.db.maintainminimum Note: ThisparameterisforusewiththeWmDBpackageonly.Ifyouareusingthe webMethodsJDBCAdaptertoconnecttoyourdatabases,seethedocumentationfor thatadapterinstead. Thisparameterappliesonlyifyouareusingserverpoolinginsteadofsession pooling,thatis,youhavespecifiedserveronthewatt.server.db.connectionCache property.Seethedescriptionofthatparameter,above,formoreinformation. Specifieshowtheserverhandlespurginginactiveconnectionsthathavetimedout.With theparametersettofalse,theserverpurgesalloftheseconnections.Withtheparameter settotrue,theserverpurgestheseconnections,butstopswhenaminimumnumberof connectionsinthepoolhasbeenreached.Youspecifytheminimumwhenyoudefinethe alias.Thispropertyisglobaltoallpools. watt.server.db.testSQL Note: ThisparameterisforusewiththeWmDBpackageonly.Ifyouareusingthe webMethodsJDBCAdaptertoconnecttoyourdatabases,seethedocumentationfor thatadapterinstead. Thisparameterappliesonlyifyouareusingserverpoolinginsteadofsession pooling,thatis,youhavespecifiedserveronthewatt.server.db.connectionCache property.Refertothewatt.server.db.connectionCacheonpage 424formore information. Specifiesifadatabaseconnectionfromaconnectionpoolisvalidorinvalid.Initially testingthedatabaseconnectionsremovesinvalidconnectionsfromtheconnectionpool andensuresthattheservicewillalwaysreceiveavalidconnection. Specifyingtruetellstheservertotestthedatabaseconnectionsintheconnectionpool.If thedatabaseconnectionisvalid,thentheserverpassestheconnectiontoaserviceto processarequest.Ifthedatabaseconnectionisinvalid,thentheserverremovesthe connectionfromtheconnectionpool. Specifyingfalsetellstheservertonottestdatabaseconnectionsintheconnectionpool. watt.server.diagnostic.logperiod Specifieshowmanyhoursoflogsarereturnedwhenyourunthediagnostictool.The defaultis6.Whenthispropertyissetto0,thediagnosticutilitydoesnotreturnanylog files.Itreturnsonlytheconfigurationalandruntimedatafiles. watt.server.dispatcher.comms.brokerPing Specifieshowoften(inmilliseconds)triggers(whichareBrokerclients)shouldpingthe Broker.WhenthereisafirewallbetweentheIntegrationServerandtheBroker,the firewallclosestheconnectionbetweenatriggerandtheBrokerwhentheconnection becomesidle.Topreventconnectionsfrombecomingidle,triggerBrokerclients periodicallypingthewebMethodsBroker.Forexample,tohavethetriggerBrokerclient pingthewebMethodsBrokerevery30seconds,specifythefollowing:
watt.server.dispatcher.comms.brokerPing=30000
425
watt.server.dispatcher.join.reaperDelay Specifieshowoften(inmilliseconds)thattheIntegrationServerremovesstate informationforcompletedandexpiredjoins.Thedefaultis1800000milliseconds(30 minutes). watt.server.email.from SpecifiestheemailaddresstheserverpresentsasitsFromaddresswhensendingemails abouterrors.Bydefault,theserverusesIntegrationServer@localhost fortheFrom Address, wherelocalhostisthenameofthehostonwhichtheIntegrationServeris running. watt.server.errorMail Specifiestheemailaddressofadministratortonotifywhentheserverencountersan internalfault.Thereisnodefault. watt.server.event.audit.async Specifieswhethertheeventhandlersfortheauditeventareinvokedasynchronouslyor synchronously.Whenthisparameterissettotrue,IntegrationServerinvokestheevent handlers(services)thatsubscribetoauditeventsasynchronously.Whenthisparameteris settofalse,IntegrationServerinvokestheeventhandlersthatsubscribetoauditevents synchronously.Thedefaultistrue. watt.server.event.exception.async Specifieswhethertheeventhandlersfortheexceptioneventareinvokedasynchronously orsynchronously.Whenthisparameterissettotrue,IntegrationServerinvokesthe eventhandlers(services)thatsubscribetoexceptioneventsasynchronously.Whenthis parameterissettofalse,IntegrationServerinvokestheeventhandlersthatsubscribeto exceptioneventssynchronously.Thedefaultistrue. watt.server.event.gd.async Specifieswhethertheeventhandlersforguaranteeddeliveryevents(gdStartandgdEnd) areinvokedasynchronouslyorsynchronously.Whenthisparameterissettotrue, IntegrationServerinvokestheeventhandlers(services)thatsubscribetoguaranteed deliveryeventsasynchronously.Whenthisparameterissettofalse,IntegrationServer invokestheeventhandlersthatsubscribetoguaranteeddeliveryeventssynchronously. Thedefaultistrue. watt.sever.event.jmsDeliveryError.async SpecifieswhethertheeventhandlersforJMSdeliveryfailureeventsareinvoked asynchronouslyorsynchronously.Whenthisparameterissettotrue,IntegrationServer invokestheeventhandlers(services)thatsubscribetoJMSdeliveryfailureevents asynchronously.Whenthisparameterissettofalse,IntegrationServerinvokesthe eventhandlersthatsubscribetoJMSdeliveryfailureeventsasynchronously.Thedefault istrue.
426
watt.server.event.jmsRetrievalError.async SpecifieswhethertheeventhandlersforJMSretrievalfailureeventsareinvoked asynchronouslyorsynchronously.Whenthisparameterissettotrue,IntegrationServer invokestheeventhandlers(services)thatsubscribetoJMSretrievalfailureevents asynchronously.Whenthisparameterissettofalse,IntegrationServerinvokesthe eventhandlersthatsubscribetoJMSretrievalfailureeventsasynchronously.Thedefault istrue. watt.server.event.replication.async Specifieswhethertheeventhandlersforreplicationeventsareinvokedasynchronously orsynchronously.Whenthisparameterissettotrue,IntegrationServerinvokesthe eventhandlers(services)thatsubscribetoreplicationeventsasynchronously.Whenthis parameterissettofalse,IntegrationServerinvokestheeventhandlersthatsubscribeto thereplicationeventssynchronously.Thedefaultistrue. watt.server.event.security.async Specifieswhethertheeventhandlerforsecurityeventsisinvokedasynchronouslyor synchronously.Whenthisparameterissettotrue,IntegrationServerinvokestheevent handlers(services)thatsubscribetosecurityeventsasynchronously.Whenthis parameterissettofalse,IntegrationServerinvokestheeventhandlersthatsubscribeto securityeventssynchronously.Thedefaultistrue. watt.server.event.session.async Specifieswhethertheeventhandlersforsessionevents(sessionStart,sessionEnd,and sessionExpire)areinvokedasynchronouslyorsynchronously.Whenthisparameterisset totrue,IntegrationServerinvokestheeventhandlers(services)thatsubscribetosession eventsasynchronously.Whenthisparameterissettofalse,IntegrationServerinvokes theeventhandlersthatsubscribetosessioneventssynchronously.Thedefaultistrue. watt.server.event.stat.async Specifieswhethertheeventhandlersforstat(statistics)eventsareinvoked asynchronouslyorsynchronously.Whenthisparameterissettotrue,IntegrationServer invokestheeventhandlers(services)thatsubscribetothestatisticsevents asynchronously.Whenthisparameterissettofalse,IntegrationServerinvokesthe eventhandlersthatsubscribetothestatisticseventssynchronously.Thedefaultistrue. watt.server.event.tx.async Specifieswhethertheeventhandlersforthetransactionevents(txStartandtxEnd)are invokedasynchronouslyorsynchronously.Whenthisparameterissettotrue, IntegrationServerinvokestheeventhandlers(services)thatsubscribetotransaction eventsasynchronously.Whenthisparameterissettofalse,IntegrationServerinvokes theeventhandlersthatsubscribetotransactioneventssynchronously.Thedefaultis true. watt.server.fileEncoding Specifiestheencodingtheserveristousewhenreadingandwritingtextfiles.This settinghasnoeffectonfilesstoredasUnicode.ThedefaultisyourJVMsfile.encoding property.
427
watt.server.ftp.listingFileAge Specifiesthenumberofsecondsthatmustelapsebeforeafilethathasbeenupdatedor createdonanIntegrationServerfunctioningasanFTPservercanbeaccessed.Files createdorupdatedwithinthetimespecifiedbythisparameterwillnotbepartofthe resultsoftheFTPLISTcommand.Thedefaultvalueis60seconds. Note: Toensurethatafilehasnotbeenupdatedrecentlyandcanberetrieved,execute anFTPLISTcommandbeforeexecutinganFTPRETRcommand. watt.server.ftp.usecommandip Controlswhetherthepub.client:ftpserviceusesconnectioninformationfromaNATserver whenconnectingtoanFTPserver. Whenthepub.client:ftpservicetriestotransferdatatoorfromanFTPserver,Integration ServerfirstconnectstotheFTPserverattheIPaddressspecifiedbythepub.client:ftp service.Inresponse,theFTPserversendsbacktheIPaddressontheFTPservertowhich IntegrationServershouldconnecttoperformthetransfer.IftheFTPserversitsbehinda NATserver,theNATserverinterceptsthisaddress,translatesit,thensendsitonto IntegrationServer. ThispropertycontrolswhetherIntegrationServerusestheaddressprovidedbytheNAT serverortheaddressalreadyspecifiedbythepub.client:ftpservice. Whenthisparameterissettotrue,IntegrationServerbypassesthetranslatedaddress andimmediatelytriestheaddressspecifiedbytheservice.Ifthisattemptfails, IntegrationServerthrowsanexception. Whenthisparameterissettofalse,thedefault,IntegrationServertriestheaddress providedbytheNATserver.Ifthatattemptfails,IntegrationServertriestheIPaddress specifiedonthepub.client:ftpservice.Ifbothattemptsfail,IntegrationServerthrowsan exception. watt.server.hostAccessMode SpecifiesIPaccessforportsthatdonothaveacustomIPaccesssetting.Whenthis parameterissetto include,theserveracceptsrequestsfromallIPaddresses,exceptthose specificallydeniedontheIntegrationServerAdministratorinterface.Whenthis parameterissettoexclude,theserverdeniesrequestsfromallIPaddressesexceptthose specificallyallowedontheIntegrationServerAdministratorinterface.Thedefaultis include. watt.server.hostAllow Specifiesthenameofthehostthatisallowedservice.Thereisnodefault. watt.server.hostDeny Specifiesthenameofthehostthatisdeniedservice.Thereisnodefault. watt.server.idr.reaperInterval Specifiestheinitialintervalatwhichthescheduledservice wm.server.dispatcher:deleteExpiredUUIDexecutesandremovesexpireddocumenthistory entries.Thedefaultis10minutes.
428
Note: Thewatt.server.idr.reaperIntervalvalueisignoredoncethe wm.server.dispatcher:deleteExpiredUUIDscheduledserviceexists.The wm.server.dispatcher:deleteExpiredUUID scheduledserviceexistsonlywhenaJDBC connectionpoolforthedocumenthistorydatabaseexistsandthepoolcontainsnon zeroconnections.Ifthisserviceexistsandyouwanttochangetheexecutioninterval, editthescheduledservice. watt.server.illegalNSChars Specifiesthecharactersthatyoucannotusewhennamingapackage,folderorservice. Thedefaultis?`-#&@^!%*:$.\ /;,~+=)(|}{][><. watt.server.invokeDirective SpecifiesanalternativewordtousefortheinvokedirectiveinURLsthatinvokeservices onIntegrationServer.Bydefault,thisparameterissetas watt.server.invokeDirectory=invoke,whichmeansusersmustspecifytheinvoke directiveasinvoke (http://host:port/invoke/folder/service_name).Toallowusersto specifytheinvokedirectiveaseitherinvokeoranalternativeword,setthisparameterto thealternativeword.Forexample,toallowuserstospecifytheinvokedirectiveaseither invokeorsubmit,(http://host:port/invoke/folder/service_nameor http://host:port/submit/folder/service_name),setthisparameteras watt.server.invokeDirectory=submit. watt.server.invoke.maxRetryPeriod Specifiesthetotalamountofwaitingtime(inmilliseconds)thatcanelapseifthe IntegrationServermakesthemaximumattemptstoretryaservice.Thedefaultis15,000 milliseconds(15seconds).Whenconfiguringretriesforanindividualservice,thevalue calculatedbymultiplyingMax attemptsvaluebytheRetry intervalcannotexceedthevalue setbythisserverparameter.Formoreinformationaboutconfiguringserviceretry,see thewebMethodsDeveloperUsersGuide. watt.server.inetaddress SpecifiestheIPaddressofthenetworkinterfacecard(NIC)onwhichtheserveristo listenforincomingrequests.Bydefault,onmultipleIPmachines,theIntegrationServer listensonallavailableIPs.TolimitthemachinetolistenonasingleIP,specifyitsaddress onthisparameter. watt.server.java.unicode SpecifieswhetherthesourcecodeforJavaservicesisstoredinUnicodeencoding.The defaultisfalse.Setthisvaluetotrueifthesourcecodecontainscharactersthatcannotbe renderedintheserversnativeencoding. watt.server.jca.connectionPool.thresholdWaitingRequest Whenenabled,thispropertyrepresentsthepercentagevaluethatisusedinadditionto theconfiguredmaximumnumberofconnections(setbytheMaximumPoolSize parameterontheConnectionspage)fortheconnectionpool.Forexample,settingthe propertyaswatt.server.jca.connectionPool.thresholdWaitingRequest=20setsthe thresholdto120%ofconfiguredmaximumnumberofconnections. Ifthepropertyisnotdefinedorifthevalueislessthanorequaltozero,thefeature remainsdisabled.
429
Whenthispropertyisenabled,theconnectionpoolensuresthatthewaitingconnection requestsplusthebusyconnectionsintheconnectionpooldonotexceedthethreshold limit. watt.server.jca.transaction.recoverOnEnlist SpecifieswhetherthetransactionmanagerwithinIntegrationServerinvokesthe XAResource.recover()servicewhenworkingwithXAtransactionsduringafailover.To indicatethattheIntegrationServershouldinvoketheXAResource.recover()service,set theparametertotrue.Otherwise,usethedefaultvalue,whichisfalse. Note: IfyouarerunningtheIntegrationServeronAIXandusingOracle9i,setthis parametertotrue. watt.server.jca.transaction.rollbackOnWriteFailure IfIntegrationServercannotstorethestatusofatransactionanditsparticipating resourcesintheXArecoverystore(forexample,becausethestoreiscorrupted),specifies whetherIntegrationServershouldtrytocontinuewiththetransactionanyway(false)or trytorollitback(true).Settingtheparametertofalseinvolvessomerisk;ifIntegration Serverendsabnormally,nostatuseswillhavebeensavedtotheXArecoverystore,and IntegrationServerwillnotbeabletoresolvetheuncompletedtransactionorgiveyouthe chancetoresolveitmanually. watt.server.jca.transaction.writeRecoveryRecord SpecifieswhetherIntegrationServermaintainsXAtransactioninformationforusewith XAtransactionrecovery.IfIntegrationServerdoesnotsaveXAtransactioninformation, uncompletedXAtransactionscannotberecoveredusingIntegrationServer.Thatis, IntegrationServerdoesnotattempttorecoverincompleteXAtransactionsautomatically andyoucannotuseIntegrationServerAdministratortomanuallyrecoverorresolvean incompletetransaction.SpecifytruetoenableXAtransactionrecovery.Specifyfalse to disableXAtransactionrecovery.Thedefaultistrue. watt.server.jdbc.defaultDriver ForusewithWmDB.SpecifiesthenameoftheJavaclassforthedriveryouwanttouseto connecttodatabaseswhennodrivernameissuppliedforadatabasealias.Thedefaultis thedrivernamefortheSunJVM:sun.jdbc.odbc.JdbcOdbcDriver. watt.server.jdbc.driverList ForusewithWmDB.SpecifiesacommadelimitedlistofJDBCdriversyouwantthe servertoloadwhenitinitializes.Thereisnodefault. watt.server.jms.wmjms.lms.readTimeout Specifiestheamountoftime(measuredinmilliseconds)thatIntegrationServerwaitsfor thenextportionofaninputstreambeforethrowingWmReadTimeoutException.The readtimeoutonlyappliesafterIntegrationServerretrievestheinitialpieceoftheinput stream.Thedefaultis30000milliseconds. watt.server.keepAliveTimeout SpecifiesalengthoftimethattheservermaintainsanopenHTTPconnectiontoaclient afteritsendsanHTTPresponsebacktotheclient.Thedefaultis15000ms(15seconds).
430
watt.server.key Specifiesthelicensekeyfortheserver.Thereisnodefault. watt.server.ldap.doNotBind SpecifieswhethertheIntegrationServerauthenticatesagainsttheLDAPserver.Ifyour IntegrationServerusesacustomauthenticationmoduleandyoudonotrequireusersto beauthenticatedagainsttheLDAPdirectory,setthispropertytotruetoprevent unnecessaryrequeststotheLDAPserver.Thedefaultisfalse. watt.server.ldap.extendedMessages ControlswhethertheIntegrationServerdisplaysadditionalinformationreturnedfrom theLDAPserverwhenanauthenticationerroroccurs.Thisinformationisavailableonly iftheLDAPserverprovidesit.ActiveDirectoryisanLDAPserverthatprovidesthis additionalinformation.Thedefaultisfalse. Whensettofalse,anerrormessagemightlooklikethis: 2005030815:40:33EST[ISS.0002.0035E]Invalidcredentialsconnectingto ldap://10.3.33.203:389/dc=KQA,dc=webMethods,dc=comas CN=bob,OU=ISUsers,DC=KQA,DC=WEBMETHODS,DC=COM Whensettotrue,thesameerrorwouldbedisplayedlikethis:
2005-03-08 15:40:33 EST [ISS.0002.0035E] Invalid credentials connecting to ldap://10.3.33.203:389/dc=KQA,dc=webMethods,dc=com as CN=bob,OU=ISUsers,DC=KQA,DC=WEBMETHODS,DC=COM: [LDAP: error code 49 - 80090308: LdapErr: DSID-0C09030F, comment: AcceptSecurityContext error, data 52e, vece]
ForActiveDirectoryusers,thedatacode(data 52eabove)containsthereasonthe authenticationfailed.Youcanconvertthecodetodecimalandlookitupon http://msdn.microsoft.com/library/enus/debug/base/system_error_codes.aspto determinetheproblem. watt.server.ldap.extendedProps SpecifiesLDAPenvironmentpropertiesthattheIntegrationServerwillpassdirectlyto anLDAPimplementationwheninitializingaJNDIcontext.Ittakesthisform:

watt.server.ldap.extendedProps=property1=value1;property2=value2;... propertyn=valuen
Forexample,ifyouareusingaspecializedJNDIproviderotherthanthedefault,orif yourLDAPdirectoryrequiresaspecialJNDIpropertytobepassedintotheenvironment whenacontextiscreated,youcouldsetthepropertycustomPropertytocustomValue:

watt.server.ldap.extendedProps=java.naming.customProperty=customValue
Thereisnodefault. watt.server.ldap.memberInfoInGroups ControlswhereIntegrationServerlooksforLDAPgroupmembershipinformation. Whensettotrue,thedefault,theIntegrationServerlooksforgroupmembership informationinthegroupobject.Whensettofalse,theIntegrationServerlooksforgroup membershipinformationintheuserobject.
431
watt.server.ldap.retryCount SpecifieshowmanytimesIntegrationServershouldautomaticallytrytoreconnecttoan LDAPserverafteranetworkoutageorLDAPserverrestart.Ifsetto0,thedefault, IntegrationServerwillprompttheLDAPuserforcredentialsratherthanretryingthe connection.Ifsettoapositiveinteger,IntegrationServerwillretrytheconnectionthe numberoftimesspecified.Thedefaultis0. watt.server.ldap.retryWait SpecifieshowlongIntegrationServershouldwaitbeforetryingtoreconnecttoanLDAP serverafteranetworkoutageorLDAPserverrestart.Whensetto0,ifthereisatransient failurewhilecommunicatingwithLDAP,IntegrationServerwillnottrytoreconnectto theLDAPserver.Ifsettoapositiveinteger,IntegrationServerwillretrytheconnection thenumberoftimesspecifiedinwatt.server.ldap.retryCountandwillwaittheamount oftimespecifiedinwatt.server.ldap.retryWaitbetweenretryattempts.Thedefaultis0. watt.server.licenses Specifiesthenumberoflicenses.Thedefaultis1. watt.server.log.maxEntries Specifiesthedefaultnumberoflogentriestobedisplayedinthelogviewingutility.The defaultis35entries(themostrecententries).Forcompleteinformation,seethe webMethodsLoggingGuide. watt.server.log.queued Specifieswhethertheserveristoqueuelogentrieswrittenbyitsfacilitiesinmemory, thenuseabackgroundthreadtowritethemtotheserverlog.Thedefaultistrue(queue logentries).Forcompleteinformation,seethewebMethodsLoggingGuide. watt.server.log.refreshInterval Specifiesthelengthoftherefreshinterval(inseconds)forlogentries.Thedefaultis90 seconds.Forcompleteinformation,seethewebMethodsLoggingGuide. watt.server.oldkey Specifiesthelicensekeythatwasinusepriortothecurrentkey.Thereisnodefault. watt.server.netEncoding Specifiestheencodingtheserveristousewhenreadingandwritingtexttothenetwork. Thissettinghasnoeffectontextthatisexplicitlyencodedinaparticularencoding.The defaultisUTF8. watt.server.noObjectURL SpecifiestheURLtowhichtheserverredirectsarequestafterthreeattemptstologonto theIntegrationServerAdministratorhavefailedbecausetheservercannotfindthe documenttheuserisrequesting.ThedefaultisfortheservertodisplayanHTMLscreen sayingNo such object. watt.server.noAccessURL SpecifiestheURLtowhichtheserveristoredirectarequestafterthreeattemptstologon totheIntegrationServerAdministratorhavefailedbecausetheuserdoesnothaveaccess totherequesteddocument.ThedefaultisfortheservertodisplayanHTMLscreen sayingAccess denied.
432
watt.server.ns.backupNodes Specifieswhetherservicesareremovedcompletelywhentheyaredeleted.Whensetto true,servicenode.ndffileswillberenamedtonode.bakwhentheyaredeleted.The defaultisfalse. watt.server.ns.dependencyManager Specifieswhetherthedependencycheckingfeaturesareenabledordisabled.Whensetto true,thedependencycheckingfeaturesidentifyelementsthatwillbeaffectedby moving,renaming,ordeletinganotherelement.Foroptimizationinaproduction environment,youmightsetthisparametertofalse.Thedefaultforthisparameteris true. Important! Documenttypesynchronizationmightnotworkproperlyifyoudisablethe dependencycheckingfeatures.Donotsetthewatt.server.ns.dependencyManager propertytofalseifyourintegrationsolutionusesdocumenttypesinthepublish andsubscribemodel. watt.server.ns.lockingModes SpecifieswhetherfilelockingisenabledontheIntegrationServer: ToenableuseoftheVersionControlSystemIntegrationfeature,setthisvaluetovcs. ToenablelocallockingontheIntegrationServersetthisvaluetofull. Todisableuserlockingandshownolocks,setthisvaluetonone. Todisableuserlockingbutshowsystemlocks,setthisvaluetosystem. watt.server.port SpecifiestheportnumberoftheIntegrationServersprimaryport.Thedefaultis5555. watt.server.portQueue SpecifiesthesizeoftheportqueueforHTTPandHTTPSports.Theportqueueisthe numberofoutstandinginboundconnectionsthatarequeuedintheTCP/IPstack.The defaultis65534.IfyourserverrunsonAS/400,setthisnumberto511. watt.server.publish.local.rejectOOS SpecifieswhetherIntegrationServershouldrejectlocallypublisheddocumentswhenthe queueforthesubscribingtriggerisatmaximumcapacity. Whenthisparameterissettotrue,beforeplacingalocallypublisheddocumentintoa subscribingtriggersqueue,IntegrationServerfirstchecksthetriggersqueuesize.Ifthe queuealreadycontainsthemaximumnumberofdocumentsallowedbythetriggers Capacityproperty,IntegrationServerrejectsthelocallypublisheddocumentforthat triggerqueueonly. Whenthisparameterissettofalse,IntegrationServercontinuestoplacelocally publisheddocumentsintoasubscribingtriggersqueueevenwhenthequeueisat capacity.Thisisthedefault. Note: Multipletriggerscansubscribetothesamedocument.IntegrationServerplaces thedocumentinanysubscribingtriggerqueuethatisnotatcapacity.
433
Note: Thisparameterappliesonlytodocumentspublishedlocallyusingthe pub.publish:publishorpub.publish.publishAndWaitservices. watt.server.publish.useCSQ SpecifieswhetherIntegrationServerusesoutboundclientsidequeuingifdocumentsare publishedwhentheBrokerisunavailable.Setthisparametertoalwaystosendpublished documentstotheoutbounddocumentstorewhentheBrokerisnotavailable.Setthis parametertonevertoinstructthepublishingservicetothrowaServiceExceptionwhen theBrokerisnotavailable.Thedefaultisalways. Note: Ifoutboundclientsidequeuingisdisabled,thepublishingserviceneedstobe writtentohandleServiceExceptionsthatoccurwhentheBrokerisnotavailable. watt.server.publish.usePipelineBrokerEvent SpecifieswhetherIntegrationServershouldbypassencodingthatisnormallyperformed whendocumentsarepublishedtotheBroker.Ifthispropertyissettotrue,Integration Serverchecksthepipelineforanobjectcalled$brokerEvent.Iftheobjectisfoundandis oftypeBrokerEvent,IntegrationServersendsitsvaluetotheBrokerandnoadditional encodingisperformed.SetthisparametertotrueifIntegrationServerissendingnative Brokerevents.Thedefaultisfalse. FormoreinformationaboutpublishingnativeBrokerevents,seethePublishSubscribe DevelopersGuide. watt.server.publish.validateOnIS SpecifieswhetherIntegrationServervalidatespublisheddocuments.Setthisparameter tooneofthefollowingvalues: Specify...
always
To... Performdocumentvalidationforallpublisheddocuments.Thisincludes instancesofpublishabledocumenttypesforwhichtheValidate when publishedpropertyissetfalse. Disabledocumentvalidationforallpublishabledocumenttypes.This includesinstancesofpublishabledocumenttypesforwhichtheValidate when publishedpropertyissettrue. Somereasonsfordisablingdocumentvalidationincludethefollowing: Youwanttoimproveperformance. Youwanttovalidatethedocumentsmanually. YouknowthatthesystemthatsentIntegrationServerthedatahas alreadyvalidatedthedata. YouprefertohavewebMethodsBroker,ratherthanIntegration Server,validatethedocuments. IntegrationServerissendingorreceivingnativeBrokerevents.
never
434
Specify...
perDoc
To... Performdocumentvalidationonlyforinstancesofpublishabledocument typesforwhichdocumentvalidationisenabled.Thatis,Integration Servervalidatespublisheddocumentsthatareinstancesofpublishable documenttypesforwhichtheValidate when publishedpropertyissettrue. Thisisthedefaultbehavior.
ForinformationabouthandlingnativeBrokereventsandspecifyingvalidationforan individualpublishabledocumenttype,seethePublishSubscribeDevelopersGuide. watt.server.requestCerts SpecifieswhethertheIntegrationServerrequestsadigitalcertificatefromclientsthat connecttoitthroughSSL.Setthisparametertotrueifyouwanttheservertorequest certificates.Setittofalseifyoudonotwanttheservertorequestcertificates.Thedefault isfalse. watt.server.revInvoke.proxyMapUserCerts ForReverseHTTPGatewayconfigurationsonly.SpecifieswhetheraReverseHTTPGateway serveristoperformclientauthenticationitselfinadditiontopassingauthentication informationtotheInternalServerforprocessing.Thedefaultisfalse.SeePerforming ClientAuthenticationontheReverseHTTPGatewayServeronpage 237formore information. watt.server.scheduler.maxWait MaximumtimeinsecondsIntegrationServerwaitsbetweenqueriesofthetaskqueue. Theserverperiodicallychecksthequeuefortasksthatarescheduledtorun.Ifthereare notaskswaitingtorun,theserverwaitsthemaxWaittimebeforecheckingthequeue again.Iftherearetaskswaitingtorun,theserverchecksagainatthetasksschedule executiontime,orafterthemaxWaittime,whicheverisearlier.Forexample,ifthe pendingtaskisduetoexecutein30secondsandthemaxWaittimeis60,theserverwill checkthequeueagainin30seconds.Thedefaultis60. IfyourunaclusterofIntegrationServersandscheduleatasktorunonallserversinthe cluster,youmightnoticetasksstartingatdifferenttimesonthedifferentserversifthe servershavedifferentsettingsforthisproperty.Forthisreason,ifyouarerunningina clusteredenvironment,alltheserversinyourclustershouldhavethesamesettingsfor thisproperty.SeewebMethodsIntegrationServerClusteringGuideformoreinformation aboutconfiguringIntegrationServersinacluster. watt.server.scheduler.threadThrottle PercentageofIntegrationServerthreadstheschedulerprocessispermittedtouse.The defaultis75%. watt.server.securePort SpecifiestheportnumberoftheIntegrationServersprimarysecuredlisteningport.The defaultis0. watt.server.serverlogQueueSize Controlsthenumberofentriesallowedintheserverlogqueue.Thispropertyisrelatedto thewatt.server.log.queuedproperty,whichcontrolswhethertheserveristowrite
435
entriesdirectlytotheserverlog,orqueuetheminmemoryfirstandthenusea backgroundthreadtowritethemtotheserverlog.Ifyourconfigurationhasthe watt.server.log.queuedpropertysettotrueandyounoticethatexpectedserverlog entriesarenotincludedinthelog,tryincreasingthequeuesize.Formoreinformation abouttheserverlogandtheserverlogqueue,seethewebMethodsLoggingGuide.The defaultqueuesizeis8192. watt.server.serviceMail Specifiestheemailaddressofanadministratortonotifywhenaservicenolongerbinds toatargetsitecorrectly.Thereisnodefault. watt.server.smtpServer SpecifiestheSMTPservertouseforservererrorloggingandserviceerroremail notification.Thereisnodefault. watt.server.smtpServerPort SpecifiesthenumberofthelisteningportontheSMTPservertowhichtheIntegration Serveristosendservererrorloggingandserviceerroremailnotification.Thedefaultis 25. watt.server.SOAP.defaultProtocol SpecifiesthedefaultprotocolthatIntegrationServerusesfornewSOAPmessages. SpecifySOAP1.1ProtocolorSOAP1.2Protocol.ThedefaultisSOAP1.1Protocol. watt.server.SOAP.directive SpecifiesadifferentwordtousefortheSOAPdirectiveinURLsthatrouterequeststothe IntegrationServerSOAPhandler.Bydefault,thisparameterissetas watt.server.SOAP.directory=soap,whichmeansusersmustspecifytheSOAPdirective assoap(http://host:port/soap).ToallowuserstospecifytheSOAPdirectiveasa differentwordinstead,setthisparametertothatword.Forexample,toallowusersto specifytheSOAPdirectiveasendpoint,(http://host:port/endpoint),setthisparameter aswatt.server.SOAP.directive=endpoint. watt.server.SOAP.MTOMThreshold Specifiesthefieldsize,inkilobytes,thatdetermineswhetherIntegrationServerhandles base64binaryencodeddatainaSOAPrequestasaMIMEattachmentorwhetheritsends itinlineintheSOAPmessage.IftheWebservicedescriptorfortheSOAPmessage enablesattachmentsfortheSOAPrequest,IntegrationServerpassesasMIME attachmentsanybase64fieldsinaSOAPmessagethatarelargerthanthethreshold.This onlyappliestoSOAP1.2messages.Thedefaultis0. watt.server.stats.avgTime Specifiesthetimeperiod(inseconds)forwhichperformancemetricsareaveraged.The defaultis10. watt.server.stats.logfile Specifiesthenameofthefiletoreceivestatistics.Thedefaultis logs\stats.log. watt.server.stats.pollTime Specifiesthenumberofsecondsbetweenupdatesofstatisticsloggings.Thedefaultis60.
436
watt.server.storage.lock.maxWait Specifiesthemaximumnumberofmillisecondsapub.storageservicewillwaittoobtain alock. watt.server.storage.lock.maxDuration Specifiesthemaximumnumberofmillisecondsapub.storageservicewillholdalock. watt.server.strictAccessExceptionLogging SpecifieswhetherIntegrationServerwilllogHTTP401AccessDeniedasanerrorand triggeranotification.Whenthispropertyissettotrue,IntegrationServerwilllogHTTP 401AccessDeniedasanerrorandtriggernotifications.Whenthispropertyissettofalse, IntegrationServerwillnotlogHTTP401AccessDeniedasanerrorandwillnottriggera notification.Thedefaultisfalse. watt.server.sync.timeout Specifiesthetimeperiodthatalockobjectexistsforagivenkey.Aftercallinga pub.sync:notifyoperation,pub.sync:waitcanbecalledwithinthistimeperiodtoreceive anotification.Thedefaultis60seconds.Thispropertyaffectsthepublicservices pub.sync:waitandpub.sync:notify. watt.server.threadPool Specifiesthemaximumnumberofthreadsthattheservermaintainsinthethreadpool thatitusestorunservices.Ifthismaximumnumberisreached,theserverwaitsuntil servicescompleteandreturnthreadstothepoolbeforerunningmoreservices.The defaultis75. watt.server.threadPoolMin Specifiestheminimumnumberofthreadsthattheservermaintainsinthethreadpool thatitusestorunservices.Whentheserverstarts,thethreadpoolinitiallycontainsthis minimumnumberofthreads.Theserveraddsthreadstothepoolasneededuntilit reachesthemaximumallowed,whichisspecifiedbythewatt.server.threadPoolMin setting.Thedefaultis10. Note: Whensettingthethreadpoolparameters(watt.server.threadPooland watt.server.threadPoolMin),beawarethateachsystemhasinherentlimitstothe numberofthreadsthatauserprocesscanspawn.Checkwithyoursystem administratortodeterminewhatthecurrentlimitsofyoursystemare,andiftheyare insufficient,askyoursystemadministratortoincreasethelimitsfortheIntegration Serverprocess. watt.server.transaction.recovery.abandonTimeout IfanerroroccurswhileIntegrationServertriestoresolveanuncompletedXA transaction,specifiesthemaximumlengthoftime(inminutes)duringwhichIntegration Servershouldmakeadditionalattempts.Thedefaultis5minutes. watt.server.transaction.recovery.sleepInterval IfanerroroccurswhileIntegrationServertriestoresolveanuncompletedXA transaction,specifiesthelengthoftime(inseconds)thatIntegrationServerwaits betweenadditionalattempts.Thedefaultis30seconds.
437
watt.server.trigger.interruptRetryOnShutdown SpecifieswhetherornotarequesttoshutdowntheIntegrationServerinterruptsthe retryprocessforatriggerservice.Ifthisparameterissettofalse,theIntegrationServer waitsforthemaximumretryattemptstobemadebeforeshuttingdown.TheIntegration Serverwillalsoshutdownifthetriggerserviceexecutessuccessfullyduringaretry attempt.Ifthisparameterissettotrue,theIntegrationServerwaitsforthecurrent serviceretrytocomplete.Ifthetriggerserviceneedstoberetriedagain(theserviceends becauseofanISRuntimeException),theIntegrationServerstopstheretryprocessand shutsdown.Uponrestart,thetransport(theBrokeror,foralocalpublish,thetransient store)redeliversthedocumenttothetriggerforprocessing.Thedefaultisfalse. Important! Ifwatt.server.trigger.interruptRetryOnShutdownissettofalseanda triggerissettoretryuntilsuccessful,atriggerservicecanenterintoaninfiniteretry situation.Ifthetransienterrorconditionthatcausesthetriggerservicetoretryisnot resolved,theIntegrationServercontinuallyreexecutestheserviceatthespecified retryinterval.Becauseyoucannotdisableatriggerduringtriggerserviceexecution andyoucannotshutdowntheserverduringtriggerserviceexecution,aninfinite retrysituationcancausetheIntegrationServertobecomeunresponsivetoa shutdownrequest. Toescapeaninfiniteretrysituation,setthe
watt.server.trigger.interruptRetryOnShutdown
totrue.Thechangetakeseffect
immediately. Note: Ifthetriggerserviceretryprocessisinterruptedandthetransportredeliversthe documenttothetrigger,thetransportincreasestheredeliverycountforthe document.Ifthetriggerisconfiguredtodetectduplicatesbutdoesnotusea documenthistorydatabaseoradocumentresolverservicetoperformduplicate detection,theIntegrationServerconsiderstheredelivereddocumenttobeIn Doubtandwillnotprocessthedocument.Formoreinformationaboutduplicate detectionandexactlyonceprocessing,seethePublishSubscribeDevelopersGuide. watt.server.trigger.keepAsBrokerEvent SpecifieswhetherIntegrationServershouldbypassdecodingthatisnormallyperformed whendocumentsareretrievedfromtheBrokeronbehalfofatrigger.Ifthispropertyis settotrue,IntegrationServerpassesthevalueoftheBrokereventtothetriggerservicein anobjectcalled$brokerEventandnodecodingisperformed.Setthisparametertotrueif IntegrationServerisreceivingnativeBrokerevents.Thedefaultisfalse. FormoreinformationaboutpublishingnativeBrokerevents,seethePublishSubscribe DevelopersGuide. watt.server.trigger.local.checkTTL SpecifieswhetherIntegrationServershouldstrictlyenforcealocallypublished documentstimetolive.Whenthisparameterissettotrue,beforeprocessingalocally publisheddocumentinatriggerqueue,IntegrationServerdetermineswhetherthe documenthasexpired.IntegrationServerdiscardsthedocumentifithasexpired.The defaultisfalse.
438
watt.server.trigger.managementUI.excludeList Specifiesacommadelimitedlistoftriggerstoexcludefromthe Broker/Local Trigger ManagementpagesintheIntegrationServerAdministrator.TheIntegrationServeralso excludesthesetriggersfromtriggermanagementchangesthatsuspendorresume documentretrievalordocumentprocessingforalltriggers.TheIntegrationServerdoes notexcludethesetriggersfromchangestocapacity,refilllevel,ormaximumexecution threadsthataremadeusingtheglobaltriggercontrols(QueueCapacityThrottleand TriggerExecutionThreadsThrottle). Youcanspecifythefullyqualifiednamesofallthetriggersthatyouwanttoexclude.You canalsousepatternmatchingtoexcludeagroupoftriggersbyspecifyingthebeginning portionofthefullyqualifiednameandfollowingitwithanasterisk(*).TheIntegration Serverexcludesalltriggersthatbeginwiththesuppliedpattern.Forexample,ifyou wanttoexcludealltriggerslocatedinthepub.prtfolder,specify:
watt.server.trigger.managementUI.excludeList = pub.prt*
watt.server.trigger.monitoringInterval Specifiestheinterval,measuredinseconds,atwhichIntegrationServerexecutesresource monitoringservicesforBroker/Localtriggers.Aresourcemonitoringserviceisaservice thatyoucreatetochecktheavailabilityofresourcesusedbyaBroker/Localtrigger service.WhenitsuspendsaBroker/Localtriggerbecauseallretryattemptshavefailed, IntegrationServerexecutestheresourcemonitoringservicetodetermineifallthe resourcesareavailable.Thedefaultis60seconds. Formoreinformationaboutresourcemonitoringservices,seethePublishSubscribe DevelopersGuide. watt.server.trigger.preprocess.suspendAndRetryOnError IndicateswhetherIntegrationServersuspendsatriggerifanerroroccursduringthe preprocessingphaseoftriggerexecution.Thepreprocessingphaseencompassesthetime fromwhenthetriggerretrievesthedocumentfromitslocalqueuetothetimethetrigger serviceexecutes.Whenthispropertyissettotrue,IntegrationServersuspendsatrigger ifoneofthefollowingoccursduringpreprocessing: ThedocumenthistorydatabaseisnotavailablewhenIntegrationServerperforms duplicatedetectionforthetrigger. Ifthedocumenthistorydatabaseisproperlyconfigured,IntegrationServersuspends thetriggerandschedulesasystemtaskthatexecutesaservicethatchecksforthe availabilityofthedocumenthistorydatabase.IntegrationServerresumesthetrigger andreexecutesitwhentheserviceindicatesthatthedocumenthistorydatabaseis available. Ifthedocumenthistorydatabaseisnotproperlyconfigured,IntegrationServer suspendsthetriggerbutdoesnotscheduleasystemtasktocheckforthedatabases availabilityandwillnotresumethetriggerautomatically.Youmustmanually configurethetriggerafterconfiguringthedocumenthistorydatabaseproperly.
439
ThedocumentresolverserviceendsbecauseofanISRuntimeException.Integration Serversuspendsthetriggerandschedulesasystemtasktoexecutethetriggers resourcemonitoringservice(ifoneisspecified).IntegrationServerresumesthe triggerandretriestriggerexecutionwhentheresourcemonitoringserviceindicates thattheresourcesusedbythetriggerareavailable.Ifaresourcemonitoringserviceis notspecified,youwillneedtoresumethetriggermanually(viatheIntegration ServerAdministratororthepub.trigger:resumeProcessingandpub.trigger:resumeRetrieval services). Whenthispropertyissettofalse,IntegrationServerdoesnotsuspendthetriggerifa preprocessingerroroccursduringtriggerexecution.Ifthedocumenthistorydatabaseis notavailable,IntegrationServerexecutesthespecifieddocumentresolverserviceto determinethestatusofthedocument.Otherwise,IntegrationServerassignsthe documentastatusofInDoubt,acknowledgesthedocument,andusestheaudit subsystemtologthedocument.Ifthedocumentresolverserviceendsbecauseofan ISRuntimeException,IntegrationServerassignsthedocumentastatusofInDoubt, acknowledgesthedocument,andusestheauditsubsystemtologthedocument. Thedefaultistrue. Formoreinformationaboutbuildingaresourcemonitoringservice,seethePublish SubscribeDevelopersGuide. watt.server.trigger.removeSubscriptionOnReloadOrReinstall SpecifieswhetherIntegrationServerdeletesdocumenttypesubscriptionsfortriggers whenthepackagecontainingthetriggerreloadsoranupdateofthepackageisinstalled. Ifthispropertyissettotrue(thedefault)andapackagereloadsoranupdateofthe packageisinstalled,IntegrationServerdeletesandthenrecreatesanydocumenttype subscriptionsfortriggersinthepackage.(IfIntegrationServerconnectstoaBroker, IntegrationServerdeletesandrecreatesthesubscriptionsonthetriggerclientonthe Broker.)Thiscreatesasmallwindowoftimeduringwhichthedocumenttype subscriptionsdonotexist.Duringthiswindow,thetriggerwillnotreceivedocumentsto whichitnormallysubscribes. Ifthispropertyissettofalse,IntegrationServerdoesnotdeleteandthenrecreate documenttypesubscriptionsfortriggerswhenthepackagereloadsorisupdated. AlthoughIntegrationServercreatesnewdocumenttypesubscriptionsfortriggers, IntegrationServerdoesnotmodifyexistingsubscriptions.Specifically,ifatriggerdeleted adocumenttypesubscription,thesubscriptionwillnotberemovedwhenthepackage reloadsorisupdated.Consequently,whenthispropertyissettofalse,thetriggermight receivedocumenttypestowhichitnolongersubscribesbecausethedeleteddocument typesubscriptionsstillexistonthetriggerclientontheBroker.Whenworkingwitha 6.5.2versionofwebMethodsBroker,youcanuseMywebMethodstodeletetheobsolete documenttypesubscriptionsfromthetriggerclientontheBroker. Thedefaultistrue. Note: ThispropertydoesnotaffecttriggersrunninginaclusterofIntegrationServers.
440
watt.server.trigger.reuseSession IndicateswhetherinstancesofaBroker/LocaltriggerusethesamesessiononIntegration ServerwhenthedocumentlocaleisthesameasthedefaultlocaleofIntegrationServer. Whenthispropertyissettotrue,IntegrationServerchecksthelocaleofthedocument beforeprocessingit.IfthedocumentlocaleisthesameasthedefaultlocaleofIntegration Server,ornolocaleisspecified,thetriggerusesasharedsession.Ifthedocumentlocaleis differentfromthedefault,thenIntegrationServercreatesanewsessionforthetriggerto usetoprocessthatdocument.Whenthispropertyissettofalse,IntegrationServeruses anewsessionforeachinstanceofatrigger.Thedefaultisfalse. ReusingsessionsforaJMStriggermightimproveperformance.However,thisproperty doesnotworkwithalladapters. watt.server.tspace.location SpecifiestheabsolutedirectorypathoftheharddiskdrivespaceinwhichtheIntegration Serveristotemporarilystorelargedocumentsratherthankeeptheminmemory.Each filethattheIntegrationServerstoresinthisdirectoryisgiventhenameDocResxxxxx.dat, wherexxxxxisavaluethatcanvaryinlengthandcharacter.Specifytheabsolute directorypathtoadirectoryonthesamemachineastheIntegrationServer.Thedefault valueisJVMstemporarydirectory(i.e.,thevalueofjava.io.tmpdir). Example:IfyouwanttheIntegrationServertousetheLargeDocTempdirectoryonyour Ddrive,specifythefollowing:
watt.server.tspace.location=D:\LargeDocTemp
Important! YoumustrestartIntegrationServerafteryoumodifythevalueofthis property. watt.server.tspace.max Specifiesthemaximumnumberofbytesthatcanbestoredatanyonetimeinthehard diskdrivespacethatyoudefinedusingthewatt.server.tspace.locationproperty.Ifthe IntegrationServerattemptstowritealargedocumenttotheharddiskdrivespacethat willcausethenumberofbytesyouspecifytobeexceeded,anerrormessageisdisplayed ontheserverconsole,andthedocumentisnotstored.Specifyapositivewholenumberof bytes.Thedefaultvalueis52,428,800bytes(50MB). Example:Tosetthemaximumnumberofbytesthatcanbestoredto30,000,000bytes, specifythefollowing:
watt.server.tspace.max=30000000
Tip! Thesizeoftheharddiskdrivespacefortemporarilysavingdocumentswillvary basedonthenumberofdocumentsthatyouprocessconcurrentlyandthesizeofthe documentsthatyouprocess.Forexample,ifyourtypicalconcurrentdocumentload is10,youwouldneedaharddiskdrivespacethatis10to15timesthecombinedsize ofthedocumentsbeingprocessedconcurrently. Important! YoumustrestarttheIntegrationServerafteryoumodifythevalueofthis property.
441
watt.server.timeToLive SpecifiestheminimumamountoftimetheTSpacewillbealive.Thisstepbecomes importantonlywhendebuggingflows.Whendebuggingflows,aftereachstep,theflow wantstocleanuptheTSpace.BysettingatimeToLive,theTSpacewontbecleaneduptill afterthedebuggingisfinished. watt.server.txMail Specifiestheemailaddressofanadministratortonotifywhenguaranteeddelivery capabilitiesaredisabledduetoanerror(forexample,iftheIntegrationServerencounters adiskfullconditionoriftheaudittraillogisfull).Thereisnodefault. watt.server.tx.cluster.lockBreakSecs Specifiesthenumberofsecondsaclusterserverwaitsbeforebreakingalockonajobina clusterjobstore.Thedefaultis120. YoumustbeusingwebMethodsIntegrationServerClusteringtousethissetting.For moreinformation,refertothewebMethodsIntegrationServerClusteringGuide. watt.server.tx.cluster.lockTimeoutMillis Specifiesthenumberofmillisecondsaclusterserversleepsbetweenattemptstoplacean updatelockonajobinaclusterjobstore.Thedefaultis100. YoumustbeusingwebMethodsIntegrationServerClusteringtousethissetting.For moreinformation,refertothewebMethodsIntegrationServerClusteringGuide. watt.server.tx.heuristicFailRetry SpecifieswhethertheIntegrationServeristoreexecuteservicesforguaranteeddelivery transactionsinthejobstorethatarependingwhentheIntegrationServerisrestarted afterafailure.Ifatransactionispending,theservicebeganexecutionbeforethe IntegrationServerfailed. Ifthesettingistrue,theIntegrationServerresetsthetransactionstatusfrompendingto new,andtheservicewillbereexecuted.Ifthesettingisfalse,theIntegrationServer resetsthetransactionstatusfrompendingtofailtoindicatetheheuristicfailure,andthe servicewillnotbereexecuted.Thedefaultistrue. watt.server.tx.sweepTime Specifiesthenumberofsecondsbetweensweeps(cleanup)ofthejobstoreforinbound guaranteeddeliverytransactions.Theserversweepsthejobstoretoremoveexpired transactions.Thedefaultis60. watt.server.userFtpRootDir SpecifiestheFTProotdirectorythattheIntegrationServerwillcreateatstartup.When anyIntegrationServeruserlogsintotheFTPListener,theservercreatesthatusersFTP homedirectoryinthisrootdirectory,forexampleFtpRoot/username.Youcanspecifyany directorytobetherootdirectory,includingamappednetworkdirectory.Ifthisproperty isnotdefined,adefaultdirectorynameduserFtpRootiscreatedinyourIntegration Serverhomedirectory.
442
Administrators,Replicators,andnonprivilegeduserscanperformputandget operationsinthefollowingdirectories: This user... Administrator Can access... admin(intheIntegrationServerhomedirectory) TheAdministratorsownuserdirectory Theentirenamespaceforallpackages,includingWmRoot Allotheruserdirectories Replicator TheIntegrationServer_directory\replicatedirectory AnyservicesinthenamespacethathaveReplicatorACLorlower TheReplicatorsownuserdirectory Nonprivileged user Theusersownuserdirectory AnyservicesthathaveanACLatorbelowtheleveloftheusers ACL
Whenausercompletesaputcommandinhisorherownuserdirectory(thatis,whenthe STORcommandiscompletedontheserversidebutbeforetheserveracknowledgesthe clientwithreturncode226),aneventisfiredtonotifyinterestedpartiesbypublishinga pub.client.ftp:putCompletedNotificationdocumenttothewebMethodsBroker.EDIpackageswill subscribetothisdocumentandwillretrievethefilejustputontotheserver. Note: TheSTOUcommandisnotsupportedontheIntegrationServer.However,itis supportedforclients.SeethefollowingbuiltinservicesinthewebMethodsIntegration ServerBuiltInServicesReference:pub.client.ftp,pub.client.ftp:put,andpub.client.ftp:mput. watt.server.users.listWmOnly SpecifieswhethertheserverdisplaysexternalusersandgroupsontheIS Administrator. Whenthisvalueissettotrue,theIS Administratordisplaysnativeusersandgroups only.Whenthevalueissettofalse(thedefault),theIS Administratoralsodisplaysusers andgroupsfromexternaldirectoriesdefinedtotheserver. watt.server.wsdl.enforceSOAPMsgPartNS Specifieswhethertheserverallowsnonnamespacequalifiedinputandoutput signaturestobespecifiedasmessagepartsforawsdlfile.Whenthisparameterissetto true(thedefault),theserverwillthrowanexceptionduringwsdlgenerationifanon namespacequalifiedinputoroutputsignatureisselected.Whensettofalse,theserver allowsnonnamespacequalifiedsignatures.Ifthisparameterissettofalse,setthe watt.server.SOAP.enforceMsgPartNSparametertofalsetoosothattheruntimesoap serviceswillalsoallownonnamespacequalifiedheaderandbodyparts. ForinteroperabilitywithotherSOAPimplementations,Software AGrecommendsthat yourunyourserverwiththisparameterenabled(thedefaultsetting).Thisensuresthat yourserverwillnotgeneratewsdlfilesthathavenonnamespacequalifiedmessage parts.
443
watt.server.xml.enforceEntityRef SpecifieswhethertheserverwillthrowanexceptionwhentheXMLparserdetectsa malformedentity.Ifthevalueissettotrue,theserverwillthrowanexceptionwhenit detectsamalformedentityinanXMLorDTD.Ifthevalueissettofalse(thedefault),the serverwillallowmalformedentitiesanddoesnotthrowanexception.
watt.tx.
watt.tx.defaultTTLMins Specifiesthedefaulttimetolive(TTL)valueforoutboundguaranteeddelivery transactions.Specifythenumberofminutesyouwanttheservertomaintainoutbound transactionsinthejobstorewhenaserviceinitiatinganoutboundtransactiondoesnot specifyaTTLvalue.Thedefaultis30. watt.tx.disabled Specifieswhetheryouwanttodisabletheuseofguaranteeddeliveryforoutbound transactions.Bydefault,theserverallowstheuseofguaranteeddeliveryforoutbound transactions.Thedefaultisfalse. watt.tx.jobThreads Specifiesthenumberofclientthreadsyouwanttomakeavailableinathreadpoolto servicependingrequestsintheoutboundguaranteeddeliveryjobstore.Thedefaultis5. watt.tx.retryBackoffTime SpecifiesthenumberofsecondstowaitafteraservicerequestfailurebeforetheJob ManagerresubmitstherequesttoexecutetheservicetotheIntegrationServer.The defaultis60. watt.tx.sweepTime Specifiesthenumberofsecondsbetweensweepsofthejobstoreofoutboundguaranteed deliverytransactions.Theserversweepsthejobstoretoidentifytransactionsthatitneeds tosubmit.Thedefaultis60.
444
watt.xslt
watt.xslt.debug.facList IdentifiesthefacilitiesforwhichtheIntegrationServerlogsXSLTinformation.The defaultis999,whichindicatesthattheIntegrationServeristologinformationforallof theXSLTfacilities.IfyoudonotwanttheIntegrationServertologinformationforanyof theXSLTfacilities,specify1000. IfyouwanttologinformationforcertainoftheXSLTfacilitiesonly,specifythenumbers forthosefacilitiesinacommadelimitedlist.Thefacilitiesareasfollows: Number 1 2 3 4 999 1000 Facility SAX JAXP XSLTservices Adminservices Allservices None Description SAXparsingrelatedinformation. JAXPrelatedinformation,includingmessagesforXML parsersandXSLTengines. XSLTservicespublicserviceinformation. XSLTservicesnonpublicadministrativeservice information. Default.Logsinformationforallservices. Willnotloginformationforanyfacilities
watt.xslt.debug.level SetsthelevelofdebugginginformationforXSLTservicesthattheIntegrationServer recordsinitslogfile.ThedefaultisthelevelthatiscurrentlysetfortheIntegration Server. watt.xslt.debug.logfile IdentifiesthefiletowhichtheIntegrationServerwritesdebugginginformation.The defaultispackages/WmXSLT/logs/xslt.log. Note: IfyoustarttheIntegrationServerfromthecommandlineusingthe-log none switch,itoverridesthevalueassignedtowatt.xslt.debug.logfileforthissession. Instead,theIntegrationServerdisplayslogginginformationonthecomputerconsole whereyoustartedtheIntegrationServer. watt.xslt.jaxp.properties SpecifiesthenameofthefiletowhichtheIntegrationServerpersistsJAXPrelated propertiesforXSLTservices.Thedefaultis packages/WmXSLT/config/transformation.properties.
445
446
Diagnosing the Integration Server

448 448 449 450 451 452
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring the Diagnostic Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Diagnostic Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Starting the Integration Server in Safe Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . When the Server Automatically Places You in Safe Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Generating a Thread Dump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
447
C Diagnosing the Integration Server
Introduction
Thisappendixcontainsinformationfortheserveradministratorwhotroubleshootsthe IntegrationServerormaintainsdiagnosticdatafromtheserver.Diagnosticdataisthe configurational,operational,andlogginginformationfromtheIntegrationServer.This informationisusefulinsituationswheretheserverbecomesunresponsiveand unrecoverable. Tofacilitatethetroubleshootingprocess,theIntegrationServerprovidesthefollowing features: Diagnostic port.Aspecialportthatusesadedicatedthreadpool. Diagnostic utility.Aspecialservicethatextractsimportantdiagnosticdatafromthe IntegrationServer. Safe mode switch.AmethodofstartingtheIntegrationServerinwhichtheserverdoes notconnecttoanyexternalresource. Thread dump.Afacilitytogeneratealogcontaininginformationaboutcurrently runningthreadsandprocesseswithinJavaVirtualMachine(JVM),tohelpdiagnose issueswithIntegrationServer.
Configuring the Diagnostic Port

Thediagnosticportisaspecialportthatusesthreadsfromadedicatedthreadpoolto processrequestssubmittedviaHTTP.ItbehaveslikeatypicalHTTPport,exceptthatthe serverusesthediagnosticthreadpoolinsteadoftheserverthreadpool. Bymaintainingaseparatethreadpool,thisportimprovesthetroubleshootingcapability whentheserverbecomesunresponsive.Forexample,whentheserverreachesits maximumnumberofthreads,youcannotopentheIntegrationServerAdministrator. Thispreventsyoufromaccessinginformationthatmighthelpyoudeterminewhythe threadsarenotavailable.Italsopreventsyoufromfreeingupotherserverresources. Usingthethreadsfromthediagnosticthreadpool,thediagnosticportenablesyouto opentheIntegrationServerAdministrator. WhenyouinstalltheIntegrationServer,itautomaticallycreatesthediagnosticportat 9999.Ifanotherportisrunningat9999,theserverwilldisablethediagnosticportwhen youstarttheIntegrationServer.Toenablethediagnosticport,youmustedittheport number.Forinstructionsabouthowtoeditportconfigurations,seeEditingaPorton page 118.OnlyonediagnosticportcanexistoneachIntegrationServer.
Diagnostic Thread Pool Configuration

ThroughtheIntegrationServerAdministrator,youcanconfigurethenumberofthreads inthediagnosticthreadpool.Theserveraddsthreadstothepoolasneededuntilit reachesthemaximumallowed.Iftheserverreachesthemaximumnumber,itwaitsuntil processescompleteandreturnsthreadstothepoolbeforebeginningmoreprocesses.
448
Youcanalsosetthethreadpriorityforthediagnosticthreadpool.Thediagnosticthread prioritydeterminestheorderofexecutionwhentheJVMreceivesrequestsfromdifferent threads.Thelargerthenumber,thehigherthepriority.WhentheJVMreceivesrequests fromdifferentthreads,itwillrunthethreadwiththehigherpriority.Therefore,by assigningahigherprioritytothethreadsinthediagnosticthreadpool,youcantake advantageofthededicatedthreadpoolandimproveaccesstotheIntegrationServer Administrator. Formoreinformationabouthowtoconfigurethediagnosticthreadpool,seeSwitching fromtheEmbeddedDatabasetoanExternalRDBMSonpage 79.
Diagnostic Port Access

OnlyusersintheAdministratorsgroupcanaccesstheserverthroughthediagnosticport. YoucanaccesstheIntegrationServerAdministratorviahttp://<hostname>:<diagnostic port>wherehostnameisthemachinethathoststheIntegrationServeranddiagnosticportis thediagnosticportnumber.Afterpromptingyouforausernameandpassword,the serverdisplaystheIntegrationServerAdministrator.Becauseyoucanaccessthe diagnosticportonlythroughHTTP,dataandpasswordswillbepassed clear=unencrypted. ThediagnosticportallowsaccessonlytoservicesdefinedwiththeAdministratorsACL. Software AGrecommendsthatyoudonotchangethedefaultaccesssettings. Note: Software AGstronglyrecommendsthatyoudiscourageanyexternaluseraccess tothediagnosticportandutility.LDAPusersshouldnotaccessthediagnosticport.
Using the Diagnostic Utility

Youusethediagnosticutilitytocollectconfigurational,operational,andloggingdata fromtheIntegrationServer.ThediagnosticutilityisanIntegrationServerservicecalled wm.server.admin:getDiagnosticData.Itdoesnottakeanyinputsandisaccessibleonlyby membersoftheAdministratorsgroup.Althoughyouruntheutilityviathediagnostic porttotroubleshoot,itcanalsobeusedwithanyHTTPorHTTPSporttocollect diagnosticdataperiodically. Thediagnosticutilitycreatesatemporarydiagnostic_data.zipfileinthe IntegrationServer\logsdirectoryandwritestothe.zipfileasitcollectsinformation. However,ifthereareproblemscreatingthe.zipfile,suchasinsufficientspaceinthefile system,itwillreturna diagnostic_data.txtfile.Inthetextfile,theconfigurationaland operationaldataareseparatedintodistinctsectionsforeasierreading.Unlikethe.zipfile, thetextfiledoesnotcontainloggingdata. Note: Eachtimeyourunthisutility,itoverwritesthediagnostic_data.zipfilethatisin theIntegrationServer\logsdirectory.Ifyouwanttokeepthepreviousfile,renameor savethefiletoanotherdirectory.
449
Tocontroltheamountofloggingdatathediagnostictoolreturns,youcanspecifythelog periodwiththewatt.server.diagnostic.logperiodparameter.Bydefault,itissetto6 hours.Whenthispropertyissetto0,theutilitydoesnotreturnanylogfiles.Itreturns onlytheconfigurationandruntimedatafiles. Thelogginginformationtheutilityreturnsdependsonhowyoustorethelogs.Ifyou savethelogstoadatabase,thediagnosticutilitywillreturntheexactnumberoflog entriesthatmatchthespecifiednumberofhours.Ifyousavethelogstothefilesystem,it willreturnnotonlytheperiodwithinthespecifiednumberofhoursbuttheentirelogfor thatday.Forinstructionsabouthowtosetserverconfigurationparameters,see SwitchingfromtheEmbeddedDatabasetoanExternalRDBMSonpage 79. Note: Thediagnosticutilitycanexecuteslowlyduetotheamountofinformation returned. To run the diagnostic utility 1 2 StartyourWebbrowser. Typethefollowingurl:
http://<hostname>:<port>/invoke/wm.server.admin/getDiagnosticData
where<hostname>istheipornameofthemachineand<port>istheportnumber wheretheIntegrationServerisrunning. 3 4 LogontotheIntegrationServerwithausernameandpasswordthathas administratorprivileges. Theserverdisplaysadialogboxthatpromptsyoutoselectoneofthefollowing: a b c Openthediagnosticdatafile. Save thediagnosticdatafiletothefilesystem. Cancelandexitthisoperation.
Ifyouopenorsavethediagnosticdatafile,theutilitycreatesthefileinthe IntegrationServer_directory\logsdirectory.
Starting the Integration Server in Safe Mode

IfIntegrationServerishavingtroublestartingbecauseitoroneofitspackagescannot connecttoanexternalresource,youcanstopIntegrationServerandthenstartitinsafe mode.WhenyoustartIntegrationServerinsafemode,itdoesnotconnecttoanyexternal resource.Inaddition,IntegrationServerloadsonlytheWmRootpackage;allother packagesareinactive. Important! Usesafemodefordiagnosticortroubleshootingpurposesonly.Donotrun anyregularIntegrationServertasksorDeveloperwhileinsafemode.Itwillreturn unpredictableresults.
450
IfIntegrationServercouldnotconnecttoaBrokerordatabase,checktheappropriate connectionparametersandmodifythemasnecessary.Forinstructions,seeUsinga64 bitJVMonSolarisandHPUXSystemsonpage 81andthewebMethodsLoggingGuide. IfapackagesuchasTradingNetworksServerorthewebMethodsSAPAdaptercould notconnecttoanexternalresource,openIntegrationServerAdministratorandgotothe Packages > Management > Activate Inactive Packagespage.IntheInactive Packageslist,select thepackageandclickActivate Package.IntegrationServerputsthepackageintothestateit wouldhavebeeninifyouhadstartedIntegrationServernormally.Forexample,ifthe packagewouldhavebeenenabled,IntegrationServerloadsandenablesit.Checkand modifytheconnectionparametersusingtheinstructionsintheappropriateguide. To start the Integration Server in safe mode 1 2 3 StoptheJavaprocessassociatedwiththeIntegrationServer(forexample,in WindowsTaskManager). Inthefilesystem,navigatetotheIntegrationServerinstallationdirectoryanddelete thefilenamedLOCKFILE. Atthecommandline,navigatetotheIntegrationServerdirectoryandenteroneofthe followingcommandstostarttheserver. System Windows UNIX Command bin\server.batsafeboot(otherswitches) bin/server.shsafeboot(otherswitches)
Forinformationaboutotherswitches,seeStartingtheServerfromtheCommand Lineonpage 31.WhenyouopentheIntegrationServerAdministrator,itwill displayamessageindicatingthattheserverisrunninginsafemode.
When the Server Automatically Places You in Safe Mode

IftheIntegrationServerdetectsaproblemwiththemasterpasswordoroutbound passwordsatstartup,itwillautomaticallyplaceyouinsafemode.Youwillseethe followingmessageintheupperleftcorneroftheServerStatisticsscreenofthe IntegrationServerAdministrator:
Theseproblemscanbecausedbyacorruptedmasterpasswordfile,acorrupted outboundpasswordfile,orbysimplymistypingthemasterpasswordwhenyouare promptedforit.Ifyoususpectyouhavemistypedthepassword,shutdowntheserver andrestartit,thistimeenteringthecorrectpassword.Ifthisdoesnotcorrecttheproblem, refertoWhenThereAreProblemswiththeMasterPasswordorOutboundPasswords atStartuponpage 248forinstructions.
451
Generating a Thread Dump

Ifyouexperienceadrasticslowdowninyourserverperformance,oranIntegration Serversubsystembecomesunresponsive,youcangenerateathreaddumptodiagnose theissue.Thethreaddumpwilldiagnosethreadresourcecontentionissueswhichmay havecausedthreadblocksordeadlocks,whichinturn,maybethecauseof unresponsiveness. Forexample,ifyourIntegrationServersprimaryHTTPportstopsacceptingnew connections,youcangenerateathreaddumpwhichmaytellyouexactlywhythe primaryportisstuck.Todothis,youmayneedtoaccessthediagnosticportwhichruns onadedicatedthread.IfyouareabletosuccessfullylogintoIntegrationServer Administrator,youcouldthengenerateathreaddump. To generate a thread dump 1 2 StartyourWebbrowser. LogontoIntegrationServerwithausernameandpasswordthathasadministrator privileges.Bydefault,IntegrationServerAdministratordisplaystheServer > Statistics page. UnderUsage,clicktheCurrentnumberofSystem Threads. TheServer > Statistics > System Threadspageisdisplayed.TheSystemThreadstable liststhreadnamesandclassifiesthemaccordingtothefollowingcategories:Alive, Daemon,andInterrupted. 4 ClickGenerate JVM Thread Dump. TheServer > Statistics > System Threads > Thread Dumppageisdisplayedwithalogof results. 5 ClickReturn to System ThreadstoreturntotheSystem Threadspage.
Forinformationaboutserverrecoverywhenahardwareorsoftwareproblemforcesyou todoaserverrestart,seeChapter 3,StartingandStoppingtheServer.
452
Wireless Communication with the Integration Server

454 456 459
How Does the Integration Server Communicate with Wireless Devices? . . . . . . . . . . . . . . . . . . Using URLs for Wireless Access to the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . WML and HDML Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
453
D Wireless Communication with the Integration Server
ThewebMethodsIntegrationServercanreceiverequestsfromandsendresponsesto Internetenabledwirelessdevices.Awirelessdevicerequestsinformationfromthe IntegrationServertheusingaURL.TheresponsessentbytheservercontainWML (WirelessMarkupLanguage)contentorHDML(HandheldDeviceMarkupLanguage) content.ExamplesofwirelessdevicesthattheIntegrationServercancommunicatewith includeInternetenabledwirelessphonesandInternetenabledpersonaldigital assistants. YoumightwanttouseawirelessdevicetocommunicatewiththeIntegrationServerto: Checkinventorylevelsatyourcompanyoratasupplier. Placeanorderorcheckthestatusofanexistingorder. Receiveorderconfirmationforanordersubmittedwithawirelessdevice. Sendorreceivenotificationtoalertsubscriberstotradefulfillmentsofsecurityprice changes. CollectstatisticsaboutyourIntegrationServerbyusingeventhandlersthatsend informationtowirelessdevices. RequestanHDMLorWMLpagestoredontheIntegrationServer. YouaccesstheIntegrationServerfromawirelessdevicebyenteringaURLintheWeb browserofwirelessdevice.TheURLcaninvokeaserviceontheIntegrationServerorcan requestaWMLorHDMLpagestoredontheIntegrationServer.
How Does the Integration Server Communicate with Wireless Devices?

TheIntegrationServercommunicateswithwirelessdevicesbymeansofawireless gateway.Thewirelessgateway(sometimescalledaWAPgateway)convertsarequest fromawirelessdevicetoanHTTPrequest.ThewirelessgatewayalsoconvertstheHTTP responsefromtheIntegrationServertoaformatunderstoodbytheWebbrowseror microbrowseronthewirelessdevice.
454
ThefollowingdiagramillustrateshowtheIntegrationServercommunicateswithan Internetenabledwirelessdevice. Communication Between the Integration Server and a Wireless Device
1 2 3
Wireless Network
Wireless Gateway
Internet
Stage
1
Description AuserrequestsaURLusingaWebbrowseronawirelessdevicesuchasa wirelessphoneorapersonaldigitalassistant(PDA).TheURLindicatesthe servicetobeinvokedoridentifiestherequestedWMLorHDMLpage.The wirelessdevicesendsanencodedrequesttothewirelessgateway. Thewirelessgateway(suchasaPhone.comsUp.LinkServerorNokiaActive Server)decodestherequestfromthewirelessdevice,createsanHTTPor HTTPSrequest(dependingonwhatisspecifiedintheURL)forthespecified URL,andsendsittotheIntegrationServer. TheIntegrationServerdoesoneofthefollowingdependingonwhattheuser requestedintheURL: ExecutestheservicespecifiedintheURLandinsertstheserviceresultsinto theassignedWMLorHDMLoutputtemplate. OR RetrievestheWMLorHDMLpagerequestedintheURL.
4 5
TheIntegrationServersendsanHTTPorHTTPSresponsetothewireless gateway. ThewirelessgatewayremovestheHTTPorHTTPSheaderfromtheresponse andsendsanencodedresponsecontainingtheHDMLorWMLcontenttothe wirelessdevice.TheWebbrowseronthewirelessdevicedecodestheresponse anddisplaystheWMLorHDMLresults.
Formoreinformationaboutwirelessgatewaysandwirelessprotocol,see www.wapforum.org.
455
Using URLs for Wireless Access to the Integration Server

TouseawirelessdevicetoaccessinformationorinvokeservicesontheIntegration Server,youneedtousethedevicesWebbrowsertoenterorselectaURL.Thefollowing sectionsexplainhowtoinvokeaservicewithaURLandhowtorequestaWMLor HDMLpagewithaURL. Note: SomeWebbrowsersforwirelessdevicesplacelimitationsonthelengthofa URLthatausercanenterorselect.MakesureanyWMLorHDMLpagesthatyou createforusewithwirelessdevicesarecompliantwithbrowserrequirements. Note: Tominimizetheamountofuserinputandthereforereducethepossibilitiesfor inputerrors,embedhyperlinkstoURLsintheWMLorHDMLpage.
Invoking a Service with a URL

YoucanuseaURLtoinvokeaservicefromanInternetenabledwirelessdevice.Youcan requestaURLbyenteringtheURLintotheWebbrowserdirectlyorbyselectingalink fortheURLthatisembeddedintoaHDMLorWMLpage.Ineithercase,theURLneeds tobeinthefollowingformat:
1 2 3 4 5
http://local:host5555/invoke/ folderName.subFolderName/serviceName?variable=value&variable=value
Item
1
Description IdentifiesthenameandportnumberfortheIntegrationServeronwhichthe serviceyouwanttoinvokeresides. Important! Forwirelessaccess,theservername(localhost)mustbearegistered domainname;thatis,theserverneedstobeaccessibleviatheInternet. Important! Manywirelessgatewaysuseport80asthedefaultregisteredport number.Ifyouwanttouseadifferentportnumber,makesuretoregisterthe servernameandportnumberwiththewirelessgateway.(Forsecurityreasons, Software AGdiscouragesusingportnumbersbelow1024.Formore information,seeSettingUpAliasesforRemoteIntegrationServerson page 68.
2 3
Specifiestherequiredkeywordinvoke,whichtellstheIntegrationServerthat theURLidentifiesaservicethatistobeinvoked. Identifiesthefolderinwhichtheservicetoinvokeresides.Separatesubfolders withperiods.Thisfieldiscasesensitive.Besuretousethesamecombinationof upperandlowercaselettersasspecifiedinthefoldernameontheIntegration Server.
456
Item
4
Description Identifiestheservicethatyouwanttoinvoke.Thisfieldiscasesensitive.Besure tousethesamecombinationofupperandlowercaselettersasspecifiedinthe servicenameontheIntegrationServer.* Specifiestheinputvaluesfortheservice.Specifyaquestionmark(?)beforethe inputvalues.Thequestionmarksignalsthebeginningofinputvalues.Each inputvalueisrepresentedasavariable=valuepair.Thevariableportioniscase sensitive.Besuretousethesamecombinationofupperandlowercaselettersas specifiedinyourservice.Ifyourservicerequiresmorethanoneinputvalue, separateeachvariable=valuepairwithanampersand(&). Note: OnlyspecifythispartoftheURLwhenusingtheHTTPGETmethod.
FormoreinformationaboutinvokingaservicewithaURL,seeBuildingaBrowser BasedClientinthewebMethodsDeveloperUsersGuide. Note: IfyouusetheURLtoinvokeaservice,makesurethattheserviceappliesthe outputtotheappropriatetemplatetype(WMLorHDML).Formoreinformation aboutcreatingoutputtemplates,seeDynamicServerPagesandOutputTemplates DevelopersGuide.
Requesting a WML or HDML Page with a URL

YoucanuseanInternetenabledwirelessdevicetorequestaWMLorHDMLpagestored ontheIntegrationServer.ByenteringaURLintheWebbrowserofawirelessdeviceor byselectingahyperlinktoaURL,youcanaccessanyWMLorHDMLpagestoredinthe followingdirectory: IntegrationServer_directory\packages\packageName\pub WherepackageNameisthenameofthepackageinwhichtheWMLorHDMLfileissaved.
457
TheURLyouenterintheWebbrowserneedstoadheretothefollowingformat:
1 2 3 4
http://localhost5555/packageName/pub/fileName
Item
1
Description IdentifiesthenameandportnumberfortheIntegrationServeronwhichthefile youwanttorequestresides. Important! Forwirelessaccess,theservername(localhost)mustbearegistered domainname;thatis,theserverneedstobeaccessibleoutsideviatheInternet. Important! Manywirelessgatewaysuseport80asthedefaultregisteredport number.Ifyouwanttouseadifferentportnumber,makesuretoregisterthe servernameandportnumberwiththewirelessgateway.(Forsecurityreasons, Software AGdiscouragesusingportnumbersbelow1024.Formore information,seeSettingUpAliasesforRemoteIntegrationServerson page 68.)
2 3
IdentifiesthepackageinwhichtheWMLorHDMLfileyouwanttorequest resides. Specifiesthepubdirectory.WMLandHDMLfilesthatcanbeservedtowireless devicesneedtoresideinthisdirectory. Note: Youdonotneedtospecifythepubdirectory.IntegrationServer automaticallylooksinpubfortherequestedfileifnodirectoryisspecified.
Identifiesthefileyouwanttorequest.
Forexample,thefollowingURLsaccessthehello.wmlfilefromthepubdirectoryforthe Wirelesspackage: http://localhost:5555/Wireless/pub/hello.wml OR http://localhost:5555/Wireless/hello.wml
458
WML and HDML Samples

ThewebMethodsIntegrationServerprovidessampleservices,WMLfiles,HDMLfiles, andoutputtemplatesthatyoucanusetoviewhowwirelessdevicescommunicatewith theIntegrationServer.Thesefilesarelocatedinthesample.wireless folderinthe WmSamplespackage.Thesesamplesprovideexamplesofservicesthatyoumightcreate toenablewirelessdevicestoorderproducts,vieworderhistory,obtainIntegration Serverstatistics,andrequestthecurrentdateandtime. Formoreinformationaboutusingthesesamples,seethefollowingfile: WmSamples\pub\WAPDemo.htm YoucanfindtheWmSamplespackageinthecertifiedsamplesareaoftheKnowledge BaseontheAdvantageWebSite.
459
460
Index
Numerics
2PC for XA transactions 388 64-bit JVM, using on Solaris and HP-UX systems 81 user accounts 48 users to a group 57, 58 Administrator user account 48 administrators adding alternate administrators 20 defining 141 defining external users as 269 email address for guaranteed delivery 325 password for predefined user account 19 predefined ACL, description 172 predefined group, description 55 predefined user account, description 19, 48 receiving messages, overview 19 responsibilities 18 role 18 SMTP server for email address for guaranteed delivery 325 Administrators ACL 172 Administrators group 55 aliases functional 78 PKI profile, deleting 209 remote servers deleting 71 identifying 69 testing connection 71 updating 71 Web services associating with a Binder 74 deleting 75 identifying 72 updating 74 Allow By Default port IP access (custom) 162 port IP access (global) 161 Anonymous ACL, description 172 Anonymous group 55 architecture, webMethods Integration Server 22 archiving packages 292 AS/400 systems, port queue size 433 Asset Publisher 82 audit-trail logging overview 28
A
Access Control Lists (ACLs) ACL used when none assigned to service 172, 176 Administrators 172 Anonymous 172 assigning to services 176 creating 173 Default 172 deleting 174 description of use 168 Developers 172 how they work with services 175 Internal 172 predefined 172 protecting use of remote server aliases 68 removing from services 177 removing protection from files 179 Replicators 172 updating 174 access file, using to control access to files 178 accessing any Web document for package 287 home page for package 287 ACLs. See Access Control Lists (ACLs) activating packages 289 activation codes, from registration authority 205 adding Access Control Lists (ACLs) 173 administrators 141 aliases for remote servers 69 aliases for Web services 72 developers 142 groups 56 packages 288 port restrictions 165, 166 ports 85 services manually 336 subscribers to packages 300
461
Index
writing log to screen 32 authenticating basic authentication 188 client certificates 182 customizing authentication with pluggable module 189 description 182 registering alternate authentication processor 194 unregistering alternate authentication processor 194 using Integrated Windows authentication 195 using user names and passwords (basic) 188 using user names and passwords with Integrated Windows authentication 195 when invalid password supplied 189 when invalid user name supplied 189 when it occurs 182 when user name not supplied 189 authentication module, creating 193 automatic pull facility 308 auxiliary PKI profile creating 206 recovering 212 when exporting a profile to an HSM device 216 available threads warning threshold 64
B
binders associating endpoint aliases 74 blocking incoming requests to server 118 Broker bypassing decoding for trigger services 438 checking for $brokerEvent objects 434 client group, description of 133 handling native events 434 keep-alive messages response time 421 retry limit 421 wait time 421 keep-alive mode 134 switching Integration Server territories 134 built-in services, for pub.pki 201, 202
C
C/C++ services, adding to server manually 336 caching service results overview 320
resetting for all services 322 resetting for single service 322 viewing statistics 322 canceling package subscriptions 315 scheduled service execution 352 capacity default document store 124 definition of 365 outbound document store 128 reducing for trigger queues 365 trigger document store 125 trigger queues 365 CAs. See certificate authorities (CAs) central user management configuring 256 disabling 259 certificate authorities (CAs) certificates to validate client certificates 186 requesting digital certificate from 150 certificate mapping changing user 187 Certificate Revocation List (CRL) description 217 stored in LDAP directory 200 when downloaded 218 certificate signing request (CSR), creating 150 Certificate Toolkit 149 certificates, digital certificates required to validate client certificates 186 description of use 147 obtaining certificate authoritys 150 requesting for server 150 trusted, for PKI profile 207 using for authentication 182 changing Access Control Lists (ACLs) 174 aliases for remote servers 71 aliases for Web services 74 license key 62 membership for groups 59 passwords 50, 51 primary port 117 scheduled service execution 350 checklists configuring server 399 deploying the server 398
462
Index
implementing SSL 148, 154 installing server 398 installing services 401 security 403 setting up user accounts, groups, and ACLs 400 classpath, using to prepare client to communicate with server 402 Clear All Duplicate or In Doubt Document Statistics link 130 client certificates certificates required to validate 186 description 182 information required to use 186 presenting multiple 154 client groups, switching 133 client prefix, for webMethods Integration Server 133 client.jar file, using to prepare client to communicate with server 402 clients authenticating 182 preparing to communicate with server 402 client-side queuing, described 127 client-side queuing, enabling or disabling 434 cluster synchronization configuring for trigger management 381 monitoring for triggers 383 Cluster View page, display of 383 clustering, in a reverse invoke configuration 222 code subdirectory 278 command line parameters for starting server 31 starting server from 31 communications with server, securing with SSL 146 configuration settings bypass list for proxy servers 77 controlling who can set 141 descriptions 408 guaranteed delivery 325 how long to keep inactive sessions 65 how to set 44 LDAP 262 license keys 62 overriding when starting server 31 ports 84 proxy servers 75 server.cnf file 44 configuring additional ports 85
bypass list for proxy servers 77 checklist 399 controlling who can configure the server 141 default document stores 123 description of all settings 408 guaranteed delivery 325 how long to keep inactive sessions 65 outbound document store 127 outbound password settings 243 PKI system settings 202 ports 84 primary port 117 proxy servers 75 server 61 server resources 79 SSL 151 SSL, checklist 148 SSL, checklist for presenting multiple client certificates 154 SSL, required information 149 trigger document store 124 user account to use 48 XA recovery store 394 controlledDeliverToTriggers 422 controlling access to services and files 168 access to services by port 158, 164 server SSL security level by port 156 who can configure the server 141 who can develop services 142 conventions used in this document 15 copying packages ACL used 172 group used 56 how to 303 publisher tasks 299 requesting subscriptions to packages 310 subscriber tasks 308 to other servers 292 user account used 48 creating Access Control Lists (ACLs) 173 auxiliary PKI profiles 206, 212 certificate signing request (CSR) 150 package release 303 packages 288 packages distribution files 303 PKI profile aliases 207
463
Index
CRL (Certificate Revocation List) description 217 in LDAP directories 200 when downloaded 218 CSR (certificate signing request), creating 150 customizing authentication 189
D
database drivers, for use with wmDB 430 database storage accessed through WmDB or JDBC adapter 78 debug mode of the server 31 decreasing capacity of trigger queues 365 document processing for concurrent triggers 373 refill level of trigger queues 365 server threads for concurrent trigger execution 373 server threads for document processing 371 server threads for document retrieval 363, 364 trigger execution for concurrent triggers 373 decrypting documents 202 decryption keys, stored in auxiliary profile 206, 212 Default ACL 172 default document store capacity 124 configuring 123 description 122 initial size 123 location 123 refill level 124 Default user account 48 defaultProtocol, SOAP 436 defining Access Control Lists (ACLs) 173 administrators 141 developers 142 groups 56 packages 288 subscribers to packages 300 user accounts 47 deleting Access Control Lists (ACLs) 174 aliases for remote servers 71 aliases for Web services 75 groups 60 packages 291 ports 117
subscribers to packages 303 user accounts 49 Deny By Default access to services through a port 164 port IP access (custom) 163 port IP access (global) 160 dependency manager, enabling and disabling 433 Developer predefined user account to use 48 privilege required to access server from 142 user account 48 developers defining 142 defining external users as 270 predefined ACL, description 172 predefined group, description 55 predefined user account, description 48 Developers ACL 172 Developers group 55 diagnostic data, description 448 diagnostic port assigning 107, 109 dedicated thread pool 448 description 448 thread priority 449 url 449 diagnostic tool url 450 watt.server.diagnostic.logperiod 450 diagnostic utility description 449 diagnostic_data.txt 449 diagnostic_data.zip 449 wm.server.admin.getDiagnosticData 449 digital certificates See also certificates certificates required to validate client certificates 186 client certificates for authentication 182 description of use 147 obtaining certificate authoritys 150 requesting 150 disabled keep-alive mode configuring 137 description of 135 disabling guaranteed delivery for outbound requests 327 packages 290
464
Index
ports 118 users 53 displaying active sessions 37, 63 documentation for packages 287 folders 334 license key 62 licensed session limit 63 log information on screen 32 membership for groups 59 package information 284 package subscribers 299 package subscriptions 309 packages 281 packages residing on your server 281 packages, enabled/disabled 283 packages, loaded/unloaded 283 scheduled service execution time 350 service information 334 service statistics 322 services 334 system task execution time 353 distribution files for packages creating 303 sending 304 DMZ, running a reverse invoke Integration Server in 220 doc subdirectory 279 document history database, removing expired entries 129, 428 document processing enforcing TTL 438 increasing or decreasing threads for 372 limiting threads for 379 overview of managing 371 rejecting locally published documents 433 resuming for all triggers 375 resuming for one trigger 377 server threads for 371 suspending for all triggers 375 suspending for one trigger 377 threads, limiting 379 document retrieval increasing or decreasing threads for 364 limiting threads for 379 overview of managing 363 resuming for all triggers 367 resuming for one trigger 369
server threads for 363 suspending and default client 368 suspending and local publishing 368 suspending for all triggers 367 suspending for one trigger 369 document stores default capacity 124 configuring size and location 123 refill level 124 outbound capacity 128 configuring size and location 127 overview 122 triggers capacity 125 configuring size and location 124 initial size 126 location 125 reducing capacity 365 refill level 125 document types removing subscriptions on reload or reinstall 440 validate when published property 434 validating 434 document types, fields from substitution groups 408 documentation additional 16 conventions used 15 feedback 16 for your packages 287 documents enforcing TTL 438 rejecting locally published 433 validating on publish 434 documents, signing 202 DSA encryption algorithm 206
E
email address for messages when guaranteed delivery fails 325, 330 ports, assigning 85 SMTP server to use for messages when guaranteed delivery fails 325, 330 Enabled icon, color descriptions 283 enabling client-side queuing 127
465
Index
packages 290 ports 119 users 53 encryption algorithms 206 encryption keys expiration 214 expiry accounts for 214 for outbound passwords 242 renewal accounts for 214 updating 214 endpoint aliases adding 72 associating with a binder 74 deleting 75 identifying 72 setting up for Web services 72 updating 74 Entrust PKI proxy, installing 216 epf files creating for PKI profile 205 for storing PKI profiles 200 errors suspending triggers for 439 Event Manager 338 eventcfg.bin file 338 events, running services in response to 338 Everybody group 55 executing replication services 338 services 26 services at scheduled times 339 shutdown services 337 startup services 337 Execution Threads Throttle property 373 expired UUIDs, deleting 428 expiry accounts, for encryption keys 214 extended settings for VCS Integration feature 116 external directories accessing users and passwords in 189 considerations for user accounts and groups 267 granting users access to services and files 271 granting users administrator privileges 269 granting users developer privileges 270 how server uses 255 overview 260 to stop using 267 uses for multiple 260 external groups
assigning administrator privileges 269 assigning developer privileges 270 assigning to ACLs 271 how server uses 255 external user accounts assigning access to services and files 271 assigning administrator privileges 269 assigning developer privileges 270 how server uses 255
F
factory class, creating 192 file age, for FTP LIST command 428 files controlling access to 177 removing Access Control List (ACL) protection from 179 filtering packages 281 firewall configuring FTP/FTPS listerner port range 115 running an internal server behind 220 flat files, sending and receiving with Trading Networks 25 flow service outbound passwords 242, 416 folders assigning Access Control List (ACLs) 176 description 332 listing 334 FTP access the directories 442 port range for listener 115 ports, assigning 85 root directory, specifying 442 ftp client timeout 411 FTP LIST command 428 FTP RETR command 428 FTPS ports, adding 98 full release, of a package 294 functional aliases, for JDBC Connection pools 78
G
gateway. See wireless gateway group name description 54 specifying for groups 54 groups adding 56
466
Index
adding users to 57, 58 administrator privileges 55 Administrators 55 Anonymous 55 changing membership 59 considerations when using external directories 267 defining 54 deleting 60 developer privileges 55 Developers 55 externally-defined 260 group name 54 overview 46 predefined 55 privileges that can be shared 54 purpose 46 Replicator 56 replicator privileges 56 settings 54 specify members of 54 specify users that belong to 47 viewing membership 59 guaranteed delivery administering 328 audit-trail log for inbound transactions 327 configuring 325 description of 324 disabling outbound transactions 327 email address and SMTP server for error notification 330 email address for error notification 325 handling heuristic failures 326 handling restart after a failure 326 inbound job store, clean up 326 inbound job store, description 325 reinitializing, for inbound transactions 329 reinitializing, for outbound transactions 330 requests to other servers 324 retry after server failure 326 retry wait 328 server failure 326 service threads 328 shutting down 328 SMTP server for error notification 325 specifying how long transactions active 328 submitting outbound transactions 328 thread pool 328
H
Handheld Device Markup Language. See HDML (Handheld Device Markup Language) HDML (Handheld Device Markup Language) 454, 457 HDML pages, accessing with wireless devices 457 heap size, increasing 122 heuristic failures, specifying how to handle for guaranteed delivery 326 home page for packages 287 hosts allowing inbound requests 160, 163 denying inbound requests 161 HSM devices for storing private keys 200 library name 204 token label 206 HTTP ports assigning 85 changing to or from primary port 117 HTTP proxy server bypass list 77 configuring 75 HTTPS ports assigning 88 changing to or from primary port 117 HTTPS proxy server bypass list 77 configuring 75
I
inbound client-side queuing, description of 127 inbound document history, description of 126 inbound vs. outbound passwords 242 inner firewall, running an internal server behind 220 installing package published from another server 316 run-time classes 402 server 398 services, checklist 401 Integrated Windows authentication activating 196 deactivating 196 description of 195 Integration Server. See webMethods Integration Server Internal ACL 172 interrupt trigger retry property 438
467
Index
IP access to ports customizing for individual ports 162 setting globally 159 IS services. See services
PKI profile 206 updating 214 used for outbound passwords 242
J
Java services adding to server manually 336 specifying compiler command 422 java.transaction.Status interface for XA transactions 390 java.transaction.xa.Xid interface for XA transactions 390 JDK, specifying non-default one to use with server 422 job store for inbound guaranteed delivery transactions 325 how long outbound transactions active 328 removing expired inbound transactions 326 submitting outbound transactions 328 JTA specification for XA transactions 390 JVM checking version when copying a package 297 using 64-bit on Solaris and HP-UX systems 81
L
label HSM device token 206 viewing slot information 210 LDAP accessing users and passwords in 189 assigning groups to ACLs 271 configuration settings 262 considerations for user accounts and groups 267 directory for use with PKI authority 203 granting users access to services and files 271 granting users administrator privileges 269 granting users developer privileges 270 how server uses 255 uses for multiple directories 260 library name, for HSM device 204 license keys changing 62 description 62 licensed sessions 63 renewal reminders 63 renewing 63 viewing 62 viewing licensed session limit 63 viewing number of active sessions 63 when session limit reached 63 listen only keep-alive mode configuring 136 description of 135 listeners. See ports listing active sessions 37 folders 334 log information on screen 32 packages residing on your server 281 services 334 Loaded? icon, color descriptions 283 loading packages 289 local document publishing enforcing TTL 438 rejecting when trigger queue is full 433 LOCKFILE, during safe mode startup 451 locking best practices 359
K
keep-alive messages idle time 421 limit 421 response time 421 keep-alive mode configuring disabled mode 137 configuring listen only mode 136 configuring normal mode 136 definition of 134 disabled mode 135 keep alive period (duration) 421 listen only mode 135 maximum response property 421 normal mode 135 response time (max response time) 421 retry limit (retryCount) 421 server parameters for 136 key pair used for SSL description 149 obtaining 149 keys, encryption expiration 214
468
Index
choosing local or VCS 356 disabling and enabling 356 locking mode, setting 433 locking out users 53 logging overview 28 write to temporary or permanent storage 420 writing log to screen 32 logging in, PKI profile 208
M
managing XA transactions 388 manifest file, for packages 279 master password (for outbound passwords) changing 244 description 242 file name and location 247 resetting when lost or corrupted 250 Maximum Documents to Send per Transaction property 127 maximum retry period, for services 429 Maximum Threads property for document processing 379 for document retrieval 379 maxPersist parameter 128 Metadata Library 82 MTOM Threshold, SOAP 436
emptying 127 maxPersist parameter 128 setting transaction limit 127 outbound passwords definition 242 encryption method, changing 246 expiration interval, changing 244 file name and location 246 flow service 242, 416 internal vs. public 416 management 243 master password, changing 244 master password, description 242 master password, file name and location 247 name or location of master password file, changing 247 name or location of outbound passwords file, changing 246 passman.props file, definition 245 resetting when master password is lost or corrupted 250 vs. inbound 242
P
packages ACL for package replication 172 activating 289 archiving 292 canceling subscriptions to 315 code subdirectory 278 controlling access 290 copying 292 copying to another server 292 creating 288 cutting 292 deleting 291 description 274 directory structure 277 disabling 290 doc subdirectory 279 documentation for 287 Enabled icon color descriptions 283 enabling 290 filtering the list 281 full vs. patch release 294 home page 287 information you can view 280 installing published package 316
N
naming services 332 native Broker events bypassing decoding for trigger services 438 checking for $brokerEvent objects 434 disabling document validation 434 NIC, specifying which one server is to listen on for incoming requests 429 normal keep-alive mode configuring 136 description of 135 ns subdirectory 279
O
outbound document store capacity 128, 423 configuring 127 defined 122 disabling use of 434
469
Index
List, filtering 281 Loaded? icon color descriptions 283 location 277 making available 290 manifest file 279 moving 292 ns subdirectory 279 package replication group 56 package replication guidelines 298 partial release 294 pasting 292 predefined 275 prohibiting access to 290 pub subdirectory 279 publishing to other servers 303 recovering 291 release 293 reloading 289 effect on trigger subscriptions 440 replicating 292, 303 residing on your server 281 resources subdirectory 279 retrieving automatically 308 retrieving manually 308 safe delete 291 sample services 277 status, enabled/disabled 283 status, loaded/unloaded 283 subscribing to 310 subscriptions to 309 tasks you can perform 288 templates subdirectory 279 updating effect on trigger subscriptions 440 user account for package replication 48 viewing information about 284 web subdirectory 279 who can subscribe to 298 partial release, of a package 294 passive FTP/FTPS listeners, port range for 115 passman.props file, definition 245 passwords See also Outbound Passwords changing 50, 51 creating for PKI profile 205 description 47 inbound vs. outbound 242 predefined Administrator user account 19
requirements 50 rules for PKI profiles 217 specifying in user accounts 47 patch release, of a package 294 PBE (Password-Based encryption), used for outbound passwords 242 persistent storage, for logging 420 pipeline Broker events bypassing decoding for trigger services 438 checking for $brokerEvent objects 434 disabling document validation 434 PKCS#5, encryption used for outbound passwords 242 PKI authority LDAP directory 203 url of 203 PKI profile aliases creating 207 deleting 209 viewing information about 210 PKI profiles assigning passwords 205 authorization code 211 auxiliary 206, 212 changing location of 215 changing password 213 creating 204, 205 creating .epf file 205 decription 200 deleting 209 deleting aliases 209 determining whether logged in 211 exporting 215 key pair algorithm 206 key strength 206 location 207 password rules 217 reference number 211 viewing information about 210 WmPKI package 201 PKI proxy description 200 installing 216 PKI system configuring settings 202 connecting server to 203, 208 PKIXCMP messages, routing through proxy 200 pluggable module
470
Index
as alternate authentication processor 189 customizing authentication with 189 port queue size, lowering for AS/400 433 ports adding 85 adding a security provider 119 configuring 84 controlling access to services through 158, 164 controlling SSL security level of 156 deleting 117 Deny By Default access to services 164 disabling 118 editing 118 email client configuration 103 enabling 119 FTP 101 FTPS 98 HTTP 85 HTTPS 88 overview 22 primary, changing 117 reasons to add additional 85 reasons to change primary 117 resetting access to 166 ports, listening adding additional 85 changing primary 117 configuring 84 deleting 117 Deny By Default access to services 164 disabling 118 enabling 119 overview 22 port range, specifying for FTP/FTPS 115 reasons to change primary 117 resetting access to 166 preprocess errors, for triggers 439 preventing access to packages 290 hosts that can connect to server 161 use of ports 118 private keys, storing on HSM devices 200 private/public key pair used for SSL description 149 obtaining 149 privileges administrator, description 141 administrator, granting 141
administrator, granting when using external directory 269 developer, description 142 developer, granting 142 developer, granting when using external directory 270 replicator 56 shared between groups 54 profile aliases, creating 207 profiles, PKI 200 auxiliary 206 changing 213 creating 204, 205 location 207 program code conventions in this document 15 protocols email (SMTP) 84 FTP 84 HTTP 84 HTTPS 84 proxy port on reverse invoke Integration Server, definition 221 web directive 167 proxy servers bypassing 77 configuring 75 installing PKI 216 overview 25 PKI 200 pub subdirectory 279 pub.pki services 201, 202 pub.trigger services resumeProcessing 378 resumeRetrieval 370 suspendProcessing 378 suspendRetrieval 370 published documents, maximum published at one time 423 publishing packages creating the distribution file 303 guidelines 298 how to 303 identifying recipients (subscribers) 300 installing published package 316 removing recipients (subscribers) 303 requesting subscriptions 310 sending the distribution file 304
471
Index
sending the release 304 updating subscriber information 301 who can publish 298 who can subscribe 298 publishing servers creating package distribution file 303 displaying subscribers 299 publishing packages 303 sending package release 304 tasks 299 who can publish 298 publishing services blocking 423 maximum published documents 423 pulling a package automatically 308 manually 308
Q
Queue Capacity Throttle, definition of 365
R
reaper interval, for document history database 428 receiving administrator messages 19 recovering packages 291 refill level default document store 124 definition of 365 reducing for trigger queues 365 trigger document store 125 Registration Authority obtaining replacement activation codes from 211 supplier of certificate activation codes 204, 205 registration port, on reverse invoke Integration Server 221 reinitializing guaranteed delivery for inbound transactions 329 guaranteed delivery for outbound transactions 330 releases (packages) creating 303 full vs. patch 294 sending 293, 304 reloading packages 289 remote servers, identifying aliases 68 Remove Expired Document History Entries link 129 removing Access Control Lists (ACLs) 174
Access Control Lists (ACLs) from services 177 expired document history entries 428 groups 60 packages 291 ports 117 scheduled execution of service 352 subscribers to packages 303 user accounts 49 renewal accounts, for encryption keys 214 renewing license key 63 replicating packages ACL 172 group 56 guidelines 298 how to 303 overview 293 publisher tasks 299 Replicator user account 299 Replicators ACL 299 Replicators group 299 requesting subscriptions to packages 310 subscriber tasks 308 user account 48 who can subscribe 298 replication services, description 338 Replicator user account 48 Replicators ACL 172 Replicators group 56 resetting access to ports 166 cache for all services 322 cache for single service 322 resolving uncompleted XA transactions 389 resource monitoring service, execution interval 439 restarting guaranteed delivery for inbound transactions 329 guaranteed delivery for outbound transactions 330 reasons for restarting server 38 server 38 restricting access to Server Administrator 141 access to server from Developer 142 access to services and files 168 access to services by port 158, 164 hosts that can connect to server 160, 163 resuming scheduled execution of service 352 retries, interrupting for shut down 438
472
Index
retry guaranteed delivery 326 reverse invoke overview 220 when clustering 222 role of administrator 18 of webMethods Integration Server 22 round robin method, in reverse invoke configuration 221 RSA encryption algorithm 206 run-time classes, installing 402
S
safe mode automatic 451 description 450 starting Integration Server in 451 scheduler server thread allotment 65 scheduling execution of services 351 canceling scheduled user task 352 changing scheduled times 350 description 339 examples of complex scheduling options 341, 342 execute one time 340 how often to execute 339 resuming scheduled user task 352 system tasks 339 user tasks 339 viewing scheduled times 350 viewing when system tasks execute 353 screens email client configuration 103 Secure Sockets Layer (SSL) background information 146 certificate signing request (CSR) 150 checklist to implement 148, 154 client certificates 182 configuring server to use 151 controlling security level by port 156 how server uses 146 information required to implement 149 information required to use client certificates 186 obtaining certificate authoritys certificate 150 obtaining private/public key pair 149 private key pair 149 requesting digital certificate 150
use of certificates 147 use of digital certificates 147 security checklist 403 checklist to implement SSL 148, 154 controlling access to services and files 168 controlling access to services by port 158, 164 controlling SSL security level by port 156 controlling who can configure the server 141 controlling who can develop services 142 information required to implement SSL 149 overview 27, 140 securing server communications 146 security provider adding 119 sending distribution files 304 releases 304 sending and receiving flat files via Trading Networks 25 server. See webMethods Integration Server Server Administrator controlling access to 141 description 19, 42 how to use 43 picture of 43 starting 42 server log message format 409 server resources 79 server security. See security server thread pool document retrieval threads 379 limiting thread usage 379 maximum threads 64 minimum threads 64 sizing 79 trigger execution threads 379 warning level 64 server threads for document processing 371 for document retrieval 363 for trigger execution 371 server.cnf description of settings 408 guaranteed delivery settings 325 how to set configuration settings 44 location 408
473
Index
updating from Server Administrator 79 services Access Control Lists (ACLs) usage 175 ACL used when no assigned ACL 172, 176 assigning Access Control Lists (ACLs) to 176 caching results, overview 320 caching service results, overview 28 canceling scheduled user task 352 changing scheduled times of execution 350 controlling access to 168 controlling access to by port 158, 164 controlling who can access 168 controlling who can develop 142 deleting its Access Control List (ACL) 175 denying access to external users 271 execution overview 26 fully-qualified names 332 granting access to external users 271 guaranteeing delivery of requests to server 324 guaranteeing delivery of responses from services 324 guidelines for using startup/shutdown/replication 338 information to schedule user tasks 339 invoking with URLs 456 listing 334 manually adding to server 336 maximum retry period 429 naming 332 overview 332 pub.pki 201, 202 removing Access Control Lists (ACLs) from 177 replication 338 replication services execution 338 resetting cache for all services 322 resetting cache for single service 322 resuming scheduled user task 352 retrieving data for 25 running in response to specific events 338 samples in WmSamples 277 scheduling execution 339 shutdown 337 shutdown service execution 337 startup 337 startup service execution 337 suspending scheduled user task 351 tasks you can perform 336 testing 336
user account for invoking trigger services 128 viewing information about 334 viewing scheduled times of execution 350 viewing service statistics 322 viewing when system tasks execute 353 sessions inactive sessions 65 maximum number allowed per license 63 stopping all 37 timeout limit 65 viewing 37 sessions, licensed limit 63 viewing active 63 viewing limit 63 shared-state client, keep-alive mode 134 shutdown services description 337 guidelines for use 338 shutting down guaranteed delivery 328 server with restart 38 webMethods Integration Server 37 sizing default document store 123 server thread pool 79 trigger document store 124 SMTP address for messages when guaranteed delivery fails 325 SMTP ports, assigning 85 SMTP server, specifying for error messages generated during guaranteed delivery processing 330 SOAP, defaultProtocol 436 SOAP, MTOMThreshold 436 specifications, viewing information about 334 SSL. See Secure Sockets Layer (SSL) starting command line parameters 31 diagnosing problems with startup 450 guaranteed delivery for inbound transactions 329 guaranteed delivery for outbound transactions 330 Server Administrator 42 server from command line 31 server on UNIX 30 server on Windows 30 server, overriding configuration settings 31
474
Index
server, process 36 startup services description 337 guidelines for use 338 stopping active sessions 37 server 37 server with restart 38 use of external directories 267 store location default document store 123 master password for outbound passwords 247 outbound passwords 246 trigger document store 125 XA recovery store 394 subscribing servers canceling subscriptions 315 displaying 299 identifying 300 installing published package 316 removing 303 requesting subscriptions 310 tasks 308 updating information for 301, 313 who can subscribe 298 subscribing to packages displaying current subscriptions 309 guidelines 298 how to 310 manually pulling current subscriptions 309 updating subscription information 313 who can subscribe 298 subscriptions canceling 315 displaying 309 installing published package 316 pulling 309 requesting from a remote server 310 substitution groups, schema 408 suspending document processing for triggers 375, 377 document retrieval for triggers 367, 369 scheduled execution of service 351 scheduled user task 351 sweep interval, ftp sessions 412 synchronization, and dependency manager 433 synchronizing, trigger management changes 380 system tasks
description 339 viewing scheduled execution 353
T
templates subdirectory 279 temporary storage, for logging 420 territories, switching for Integration Server 134 testing connection to remote servers 71 installation of server 404 services 336 thread dump, generating 452 thread pool limiting server thread usage 379 scheduler 65 server 79 warning threshold 64 threads for document processing 372, 379 for document retrieval 363, 379 threshold, server thread availability 64 throttle controls Execution Threads Throttle 373 Queue Capacity Throttle 365 time to live (TTL), specifying for guaranteed delivery 328 timeout limits, for sessions 65 token, label 206 Trading Networks, sending flat files to 25 transaction logs inbound guaranteed delivery transactions 327 transaction management (XA) 388 trigger removing subscriptions 440 trigger document store capacity 125 configuring 124 decription 122 initial size 126 location 125 reducing capacity 365 refill level 125 triggers cluster synchronization 380 configuring 381 log messages for 381 monitoring 383 concurrent, reducing execution threads 373
475
Index
deleting document type subscriptions 440 document processing concurrent trigger execution threads 373 limiting threads 379 overview 371 rejecting when queue is full 433 resuming for all triggers 375 resuming for one trigger 377 suspending for all triggers 375 suspending for one trigger 377 thread usage 371, 372 document retrieval overview 363 resuming for all triggers 367 resuming for one trigger 369 suspending for all triggers 367 suspending for one trigger 369 thread usage 363 editing properties 384 interrupting retries 438 monitoring interval 439 queue capacity, reducung 365 refill level, reducing 365 resuming all document processing 375 resuming document processing 375, 377 resuming document retrieval 367, 369 retrying on error 439 reuse sessions 441 shut down requests 438 specifying user account 128 suspending on error 439 throttle controls Execution Threads Throttle 373 Queue Capacity Throttle 365 troubleshooting information 16 trusted certificates configuring the server to use SSL 152 for PKI profile 207 tspace location 441 maximum bytes 441 TTL (time to live), specifying for guaranteed delivery 328 two-phase commit for XA transactions 388 typographical conventions in this document 15
U
unauthenticated users, predefined group description 55 UNIX, starting webMethods Integration Server 30 updating Access Control Lists (ACLs) 174 aliases for remote servers 71 aliases for Web services 74 license key 62 membership for groups 59 subscriber information 301 subscription information 313 when services scheduled to execute 350 URLs accessing the server with 456 invoking services with 456 using to access HDML or WML pages 457 user accounts account to configure and manage server 48 account to use when connecting from Developer 48 adding 48 Administrator 19 considerations when using external directories 267 deleting 49 description 47 externally-defined 260 group membership 47 overview 46 password 47 predefined 48 purpose 46 settings 47 trigger service execution 128 user name 47 using to authenticate (basic) 188 using to authenticate with Integrated Windows authentication 195 when client does not supply a user name 48 user name externally-defined 260 specifying in user account 47 using to authenticate (basic) 188 using to authenticate with Integrated Windows authentication 195 user tasks canceling scheduled execution 352
476
Index
changing when scheduled to execute 350 examples of complex scheduling options 341, 342 information to schedule services 339 resuming scheduled execution 352 schedule to execute one time 340 suspending scheduled execution 351 viewing when scheduled to execute 350 userFtpRootDir property 442 users authenticating 182 disabling 52, 53 enabling 52, 53 locking out 52
V
Validate when published property 434 version control, enabling locking for 433 versions, checking when a package is copied 297 viewing active sessions 37, 63 documentation for packages 287 folders 334 license key 62 licensed session limit 63 membership for groups 59 package information 284 package subscriptions 309 packages 281 packages residing on your server 281 service information 334 service statistics 322 services 334 subscribers to packages 299 when services scheduled to execute 350 when system tasks execute 353 whether packages are enabled/disabled 283 whether packages are loaded/unloaded 283
W
WAP gateway. See wireless gateway warning threshold, server thread availabliity 64 watt 427 watt.core.schema.generateSubstitutionGroups 408 watt.core.validation.multipleroot 408 watt.debug.layout 409 watt.debug.level 409 watt.debug.logfile 327, 410
watt.debug2.facList 410 watt.debug2.logstringfile 410 watt.net.email.validateHost 411 watt.net.ftpClientDataConnTimeout 411 watt.net.ftpClientTimeout 411 watt.net.ftpConnTimeout 411 watt.net.ftpPassiveLocalAddr 411 watt.net.ftpPassivePort.max 115, 412 watt.net.ftpPassivePort.min 115, 412 watt.net.ftpSweepInterval 412 watt.net.ftpUseCertMap 412 watt.net.httpChunkSize 413 watt.net.maxClientKeepaliveConns 413 watt.net.maxRedirects 413 watt.net.proxyHost 413 watt.net.proxyPass 413 watt.net.proxyPort 413 watt.net.proxySkipList 413 watt.net.proxyUser 414 watt.net.retries 414 watt.net.secureProxyHost 414 watt.net.secureProxyPass 414 watt.net.secureProxyPort 414 watt.net.secureProxyUser 414 watt.net.ssl.client.hostnameverification 414 watt.net.ssl.client.strongcipheronly 414 watt.net.ssl.server.clientHandshakeTimeout 414 watt.net.ssl.server.strongcipheronly 415 watt.net.timeout 415 watt.net.useCookies 415 watt.net.userAgent 415 watt.net.webapp.cookies.useRelevantPath 415 watt.security.caCert 416 watt.security.CADir 416 watt.security.cert.wmChainVerifier.trustByDefault 416 watt.security.fips.mode 416 watt.security.ope.AllowInternalPasswordAccess 416 watt.security.pki.jnditimeout 417 watt.security.privateKey 417 watt.security.signedCert 417 watt.security.ssl.cacheClientSessions 417 watt.security.ssl.ignoreExpiredChains 417 watt.security.ssl.keypurposeverification 417 watt.server 418 watt.server.allowDirective 418 watt.server.auditDBSize 418
477
Index
watt.server.auditDir 418 watt.server.auditDocIdField 418 watt.server.auditFetchSize 419 watt.server.auditGuaranteed 419 watt.server.auditLog 419 watt.server.auditLog.error 419 watt.server.auditLog.gd 419 watt.server.auditLog.session 419 watt.server.auditMaxPool 419 watt.server.auditMinPool 419 watt.server.auditRetryCount 420 watt.server.auditSync 420 watt.server.auditThreshold 420 watt.server.broker.producer.multiclient 420 watt.server.broker.replyConsumer.fetchSize 420 watt.server.broker.replyConsumer.multiclient 420 watt.server.broker.replyConsumer.sweeperInterval 420 watt.server.brokerTransport.dur 136, 421 watt.server.brokerTransport.max 136, 421 watt.server.brokerTransport.ret 136, 421 watt.server.cache.flushMins 421 watt.server.cache.gcMins 421 watt.server.cache.isPersistent 421 watt.server.clientTimeout 422 watt.server.cluster.aliasList 422 watt.server.cluster.aware 422 watt.server.cluster.cacheName 422 watt.server.cluster.SessTimeout 422 watt.server.compile 422 watt.server.compile.unicode 422 watt.server.control.controlledDeliverToTriggers 422 watt.server.control.maxPersist 128, 423 watt.server.control.maxPublishOnSuccess 423 watt.server.cron.maxThreads 423 watt.server.cron.minThreads 423 watt.server.date.suppressPatternError 424 watt.server.dateStampFmt 423 watt.server.db.blocktimeout 424 watt.server.db.connectionCache 424 watt.server.db.maintainminimum 425 watt.server.db.testSQL 425 watt.server.diagnostic.logperiod 425, 450 watt.server.dispatcher.join.reaperDelay 426 watt.server.email.from 426 watt.server.errorMail 426 watt.server.event.audit.async 426 watt.server.event.exception.async 426
watt.server.event.gd.async 426 watt.server.event.jmsRetrievalError.async 427 watt.server.event.replication.async 427 watt.server.event.security.async 427 watt.server.event.session.async 427 watt.server.event.stat.async 427 watt.server.event.tx.async 427 watt.server.extendedMessages 431 watt.server.fileEncoding 427 watt.server.ftp.listingFileAge 428 watt.server.ftp.usecommandip 428 watt.server.hostAccessMode 428 watt.server.hostAllow 428 watt.server.hostDeny 428 watt.server.idr.reaperInterval 428 watt.server.illegalNSChars 429 watt.server.inetaddress 429 watt.server.invoke.maxRetryPeriod 429 watt.server.java.unicode 429 watt.server.jca.transaction.recoverOnEnlist 430 watt.server.jca.transaction.rollbackOnWriteFailure 395, 430 watt.server.jca.transaction.writeRecoveryRecord 393 watt.server.jdbc.defaultDriver 430 watt.server.jdbc.driverList 430 watt.server.jms.wmjms.lms.readTimeout 430 watt.server.keepAliveTimeout 430 watt.server.key 431 watt.server.ldap.doNotBind 191, 431 watt.server.ldap.extendedProps 431 watt.server.ldap.memberInfoInGroups 431 watt.server.ldap.retryCount 432 watt.server.ldap.retryWait 432 watt.server.licenses 432 watt.server.log.maxEntries 432 watt.server.log.queued 432 watt.server.log.refreshInterval 432 watt.server.noAccessURL 432 watt.server.noObjectURL 432 watt.server.ns.backupNode 433 watt.server.ns.dependencyManager 433 watt.server.ns.lockingMode 433 watt.server.oldkey 432 watt.server.port 433 watt.server.portQueue 433 watt.server.publish.local.rejectOOS 433 watt.server.publish.useCSQ 434
478
Index
watt.server.publish.usePipelineBrokerEvent 434 watt.server.publish.validateOnIS 434 watt.server.requestCerts 435 watt.server.revInvoke.proxyMapUserCert 435 watt.server.scheduler.maxWait 435 watt.server.scheduler.threadThrottle 435 watt.server.securePort 435 watt.server.serverlogQueueSize 435 watt.server.serviceMail 436 watt.server.smtpServer 325, 436 watt.server.smtpServerPort 436 watt.server.SOAP.defaultProtocol 436 watt.server.SOAP.MTOMThreshold 436 watt.server.stats.avgTime 436 watt.server.stats.logfile 436 watt.server.stats.pollTime 436, 437 watt.server.storage.lock.maxDuration 437 watt.server.strictAccessExceptionLogging 437 watt.server.sync.timeout 437 watt.server.threadPool 437 watt.server.threadPoolMin 437 watt.server.transaction.recovery.abandonTimeout 394, 437 watt.server.transaction.recovery.sleepInterval 394, 437 watt.server.trigger.interruptRetryOnShutdown 438 watt.server.trigger.keepAsBrokerEvent 438 watt.server.trigger.local.checkTTL 438 watt.server.trigger.managementUI.excludeList 439 watt.server.trigger.monitoringInterval 439 watt.server.trigger.preprocess.suspendAndRetryOn Error 439 watt.server.trigger.removeSubscriptionOnReloadOr Reinstall 440 watt.server.trigger.reuseSession 441 watt.server.tspace.location 441 watt.server.tspace.max 441 watt.server.tx.cluster.lockBreakSecs 442 watt.server.tx.cluster.lockTimeoutMillis 442 watt.server.tx.heuristicFailRetry 326, 442 watt.server.tx.logfile 327 watt.server.tx.sweepTime 326, 442 watt.server.txMail 325, 442 watt.server.userFtpRootDir 442 watt.server.users.listWmOnly 443 watt.server.wsdl.enforceSOAPMsgPartNS 443 watt.sever.event.jmsDeliveryError.async 426 watt.tx.defaultTTLMins 328, 444
watt.tx.disabled 327, 444 watt.tx.jobThreads 328, 444 watt.tx.retryBackoff 328 watt.tx.retryBackoffTime 444 watt.tx.sweepTime 328, 444 watt.xslt.debug.facList 445 watt.xslt.debug.level 445 watt.xslt.debug.logfile 445 watt.xslt.jaxp.properties 445 web directive, using with proxy port 167 Web services adding endpoint aliases 72 associating an endpoint alias with a binder 74 endpoint aliases deleting 75 updating 74 identifying endpoint aliases 72 setting up endpoint aliases 72 web subdirectory 279 webMethods Integration Server accessing with URLs 456 architecture 22 audit-trail logging, overview 28 client authentication 182 client groups, switching 133 client prefix 133 configuration settings 408 configuring 61 debug mode 31 deploying 398 determining if running 36 how SSL is used 146 identify hosts that can connect 160, 163 installing 398 license keys 62 overview 22 preventing use of port 118 process for executing services 26 process when starting 36 recovery after hardware or software failure 38 rejecting connections from specified hosts 161 requesting digital certificate 150 restarting 38 retrieving data for services 25 role 22 running as a Windows service 34 security overview 27, 140 setting up aliases for remote servers 68
479
Index
setting up aliases for Web services 72 setting up multiple Integration Servers to run as NT services 35 shutting down 37 starting from command line 31 starting on UNIX 30 territories, switching 134 testing installation 404 using with wireless gateways 454 when to restart 38 wireless devices, communicating with 454 wireless devices, using with 454 Windows authentication, See Integrated Windows authentication wireless devices communicating with webMethods Integration Server 454 invoking services with URLs 456 requesting HDML or WML pages 457 using URLs to access servers 456 using with webMethods Integration Server 454 wireless gateway, role in wireless communication 454 Wireless Markup Language. See WML (Wireless Markup Language) wm.server.admin getDiagnosticData 449 wm.server.dispatcher:deleteExpiredUUID service 129, 428 WML (Wireless Markup Language) 454, 457 WML pages, accessing with wireless devices 457 WmPKI package, for use with PKI profiles 201 WmSamples package, description 277
resolving uncompleted transactions automatically 389 resolving uncompleted transactions manually 395 setting action to take when status not stored 395, 430 setting retry period for automatic resolution 394, 437 setting time limit for automatic resolution 394, 437 uncompleted transactions Integration Server cannot resolve 390 XA interface 388 XIDs 390 XIDs 388, 390
Z
zip files for packages creating 303 sending 304
X
XA recovery store 388 configuring 394 description 388 initial size 394 location 394 XA transactions deleting unresolved 395 disabling recovery 393 effect on Integration Server performance 389 enabling recovery 393 errors during manual recovery 396 JTA specification 390 management 388
480

7-1-1 Integration Server Administrators Guide

Caricato da

Informazioni sul documento

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

7-1-1 Integration Server Administrators Guide

Caricato da

Copyright:

Formati disponibili

TitlePage

webMethods Integration Server

Copyright & Docu mentID

Document ID: IS-AG-711-20080731

webMethods Integration Server Administrators Guide Version 7.1.1

webMethods Integration Server Administrators Guide Version 7.1.1

webMethods Integration Server Administrators Guide Version 7.1.1

webMethods Integration Server Administrators Guide Version 7.1.1

webMethods Integration Server Administrators Guide Version 7.1.1

webMethods Integration Server Administrators Guide Version 7.1.1

webMethods Integration Server Administrators Guide Version 7.1.1

webMethods Integration Server Administrators Guide Version 7.1.1

webMethods Integration Server Administrators Guide Version 7.1.1

webMethods Integration Server Administrators Guide Version 7.1.1

webMethods Integration Server Administrators Guide Version 7.1.1

webMethods Integration Server Administrators Guide Version 7.1.1

About This Guide

webMethods Integration Server Administrators Guide Version 7.1.1

About This Guide

webMethods Integration Server Administrators Guide Version 7.1.1

The Role of the Administrator

webMethods Integration Server Administrators Guide Version 7.1.1

1 The Role of the Administrator

What Does an Administrator Do?

Typical Administrative Responsibilities

webMethods Integration Server Administrators Guide Version 7.1.1

1 The Role of the Administrator

The Integration Server Administrator

Receiving Administrative Messages from the Server

The Administrator User

The Administrators Password

webMethods Integration Server Administrators Guide Version 7.1.1

1 The Role of the Administrator

Adding Backup Administrators

webMethods Integration Server Administrators Guide Version 7.1.1

An Overview of the Server

webMethods Integration Server Administrators Guide Version 7.1.1

2 An Overview of the Server

The Role of the Server

webMethods Integration Server Administrators Guide Version 7.1.1

2 An Overview of the Server

FTPS requests FTPS Port Email message

IMAP or POP3 Server

File Polling Port

webMethods Integration Server Administrators Guide Version 7.1.1

2 An Overview of the Server

File Polling Port

Whenaclientinvokesaservice,thatservicerunsasathreadwithintheIntegration Serverprogram.Dependingonwhatfunctiontheserviceistoaccomplish,itcanalso createadditionalthreadstoperformtaskssimultaneously.

webMethods Integration Server Administrators Guide Version 7.1.1

2 An Overview of the Server

Retrieving Data for Services

webMethods Integration Server Administrators Guide Version 7.1.1

2 An Overview of the Server

optional Proxy Server HTTP requests

webMethods Integration Server

HTTP Port HTTPS Port

Proxy Server Internet

IMAP or POP3 Server

File Polling Port

How the Server Executes Services

webMethods Integration Server Administrators Guide Version 7.1.1

2 An Overview of the Server

webMethods Integration Server Administrators Guide Version 7.1.1

2 An Overview of the Server