webMethods Integration Server Administrator’s Guide

Version 9.8

April 2015

This document applies to webMethods Integration Server Version 9.8 and to all subsequent releases.

Specifications contained herein are subject to change and these changes will be reported in subsequent release notes or new editions.

Copyright © 2007-2017 Software AG, Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA, and/or its subsidiaries and/orits affiliates and/or their licensors.

The name Software AG and all Software AG product names are either trademarks or registered trademarks of Software AG and/orSoftware AG USA Inc. and/or its subsidiaries and/or its affiliates and/or their licensors. Other company and product names mentionedherein may be trademarks of their respective owners.

Detailed information on trademarks and patents owned by Software AG and/or its subsidiaries is located athp://softwareag.com/licenses.

Use of this software is subject to adherence to Software AG's licensing conditions and terms. These terms are part of the productdocumentation, located at hp://softwareag.com/licenses and/or in the root installation directory of the licensed product(s).

This software may include portions of third-party products. For third-party copyright notices, license terms, additional rights orrestrictions, please refer to "License Texts, Copyright Notices and Disclaimers of Third Party Products". For certain specific third-partylicense restrictions, please refer to section E of the Legal Notices available under "License Terms and Conditions for Use of Software AGProducts / Copyright and Trademark Notices of Software AG Products". These documents are part of the product documentation, locatedat hp://softwareag.com/licenses and/or in the root installation directory of the licensed product(s).

Document ID: IS-AG-98-20180519

http://softwareag.com/licenses/http://softwareag.com/licenses/http://softwareag.com/licenses/

MTable of Contents

webMethods Integration Server Administrator’s Guide Version 9.8 3

Table of Contents

About this Guide............................................................................................................................25Document Conventions............................................................................................................ 25Online Information.................................................................................................................... 26

The Role of the Administrator......................................................................................................27What Does an Administrator Do?............................................................................................ 28Typical Administrative Responsibilities.....................................................................................28The Integration Server Administrator....................................................................................... 29Receiving Administrative Messages from the Server...............................................................29The Administrator User.............................................................................................................29

The Administrator's Password...........................................................................................29Adding Backup Administrators................................................................................................. 30

An Overview of the Server........................................................................................................... 31The Role of the Server.............................................................................................................32

About the Integration Server Default and Named Instances.............................................32Architecture............................................................................................................................... 33

Services............................................................................................................................. 35Retrieving Data for Services............................................................................................. 35

How the Server Executes Services..........................................................................................37How the Server Loads Java Classes.......................................................................................38

Class Loaders....................................................................................................................38OSGi Bundle Class Loader........................................................................................39Integration Server Class Loaders.............................................................................. 39

Classpaths......................................................................................................................... 40How the Integration Server Classpaths Are Specified............................................... 40Changing Classpath Information at Startup............................................................... 42

How Class Loading Works................................................................................................ 43Class Loading Process.............................................................................................. 43

Scenario One: Integration Server Knows Where the Class Lives.......................44Scenario Two: Integration Server Does Not Know Where the Class Lives......... 45Scenario Three: Package Class Loader Does Not Defer to the Integration ServerClass Loader....................................................................................................... 45

Where to Place Classes and Jar Files for Packages........................................................46Where to Place Custom and Third-Party Jar Files........................................................... 47Accelerating Class Loading...............................................................................................47

Integration Server Security....................................................................................................... 48Logging..................................................................................................................................... 49Caching..................................................................................................................................... 49

Starting and Stopping the Server................................................................................................ 51Starting the webMethods Integration Server............................................................................52

MTable of Contents

webMethods Integration Server Administrator’s Guide Version 9.8 4

Starting the Default Integration Server Instance on Windows...........................................52Starting Integration Server on UNIX................................................................................. 52Starting a Server Instance from the Command Prompt....................................................53

What Happens When You Start the Server?........................................................................... 59How to Tell if the Server Is Running Correctly..................................................................59

Running Integration Server as a Windows Application vs. a Windows Service....................... 60Switching the Server from a Windows Service to a Windows Application........................ 61Switching the Server from a Windows Application to a Windows Service........................ 61

Passing Java System Properties to Integration Server............................................................62Shutting Down the Integration Server...................................................................................... 63

Shutting Down the Integration Server from Integration Server Administrator....................63Shutting Down the Integration Server from the Command Prompt...................................63

Viewing Active Sessions...........................................................................................................64Viewing the Integration Server Process ID.............................................................................. 64Restarting the Integration Server............................................................................................. 65Server Recovery....................................................................................................................... 65

Integration Server Data Integrity and Recoverability Considerations................................66Critical Integration Server Data Files......................................................................... 66

The Java Service Wrapper.......................................................................................................67The Java Service Wrapper Configuration Files................................................................ 67JVM Configuration............................................................................................................. 68The Wrapper Log.............................................................................................................. 68

Logging Properties..................................................................................................... 69Fault Monitoring.................................................................................................................70Generating a Thread Dump.............................................................................................. 70

Running Multiple Integration Server Instances.......................................................................... 71Overview................................................................................................................................... 72Guidelines for Running Multiple Integration Server Instances on the Same Machine.............. 72About Creating a New Integration Server Instance..................................................................72About the is_instance Script.....................................................................................................73

Syntax................................................................................................................................ 73is_instance Script Commands...........................................................................................73

Creating a New Integration Server Instance............................................................................ 74Installing and Updating Packages on a Server Instance......................................................... 76Deleting Packages from a Server Instance..............................................................................77Updating Language Packs on a Server Instance.....................................................................78Deleting a Server Instance.......................................................................................................79

Using the Integration Server Administrator................................................................................81What Is the Integration Server Administrator?......................................................................... 82Starting the Integration Server Administrator........................................................................... 82Accessing Integration Server Administrator through My webMethods..................................... 83Basic Operation........................................................................................................................ 84

Logging Off the Integration Server Administrator..............................................................85Getting Help.......................................................................................................................85

MTable of Contents

webMethods Integration Server Administrator’s Guide Version 9.8 5

The Configuration File.............................................................................................................. 85Software AG Command Central...............................................................................................85

Managing Users and Groups........................................................................................................87Users and Groups.................................................................................................................... 88

Purpose of Users and Groups.......................................................................................... 88Defining a User Account.......................................................................................................... 89

Predefined User Accounts.................................................................................................89Adding User Accounts.......................................................................................................90Removing User Accounts..................................................................................................91Adding an Administrator User........................................................................................... 92Adding a Developer User..................................................................................................93Changing Passwords.........................................................................................................94Setting Password Requirements....................................................................................... 95

Disabling and Enabling Users.................................................................................................. 96Disabling a User................................................................................................................96Enabling a User.................................................................................................................97

Defining Groups........................................................................................................................97Predefined Groups............................................................................................................ 98Adding Groups...................................................................................................................99Adding Users to a Group................................................................................................ 100Removing Users from a Group....................................................................................... 101Viewing Group Membership............................................................................................ 102Removing Groups............................................................................................................103

Configuring the Server................................................................................................................105Viewing and Changing Licensing Information........................................................................ 106

The License Key..............................................................................................................106Viewing Licensing Information..................................................................................106Changing Licensing Information...............................................................................106Renewal Reminders................................................................................................. 107Renewing a Key.......................................................................................................107Adding Licensed Features....................................................................................... 107

Licensed Sessions...........................................................................................................107Viewing Active Sessions.......................................................................................... 108

Managing the Server Thread Pool......................................................................................... 108Managing Server Sessions.....................................................................................................110

Setting the Session Timeout Limit.................................................................................. 110Setting the Stateful Session Limit................................................................................... 111

Configuring Outbound HTTP Settings....................................................................................112Specifying Outbound HTTP Settings.............................................................................. 114

Setting Up Aliases for Remote Integration Servers............................................................... 115Adding an Alias for a Remote Integration Server........................................................... 116Testing the Connection to a Remote Server...................................................................118Editing an Alias............................................................................................................... 118Deleting an Alias............................................................................................................. 118

MTable of Contents

webMethods Integration Server Administrator’s Guide Version 9.8 6

Specifying Third-Party Proxy Servers for Outbound Requests.............................................. 119How Integration Server Uses Proxy Servers.................................................................. 119Creating a Proxy Server Alias.........................................................................................121Editing a Proxy Server Alias........................................................................................... 124Disabling a Proxy Server Alias........................................................................................125Enabling a Proxy Server Alias........................................................................................ 125Specifying a Default Proxy Server Alias......................................................................... 125Deleting a Proxy Server Alias......................................................................................... 126Bypassing a Proxy Server...............................................................................................126

Configuring Where the Integration Server Writes Logging, Status, and Other Information.....127Switching from the Embedded Database to an External RDBMS..........................................127Working with Extended Configuration Settings...................................................................... 128Configuring Integration Server to Work with Servers Running HTTP 1.0 and Above.............129Specifying Character Encoding.............................................................................................. 129Configuring the JVM...............................................................................................................130Specifying the JDK or JRE for Integration Server..................................................................130Changing the JVM Heap Size Used by Integration Server.................................................... 131Publishing and Retracting Information about Integration Server Assets................................ 132

Configuring Integration Server to Connect to CentraSite................................................132Testing the Connection to CentraSite............................................................................. 133

Setting a Port for Remote Client JMX Monitoring.................................................................. 134Configuring Integration Server to Accept a Debug Connection During Startup......................134Using CORS with Integration Server......................................................................................135

How Integration Server Handles CORS Requests..........................................................135Configuring Integration Server to Accept CORS Requests.............................................135

Managing JDBC Pools................................................................................................................ 139Overview................................................................................................................................. 140Managing Functional Alias Definitions................................................................................... 141

Assigning Connection Pools to Functional Aliases......................................................... 141Testing Functional Aliases...............................................................................................142Restarting Functional Aliases..........................................................................................143

Managing Pool Aliases...........................................................................................................143Creating Connection Pool Aliases Manually................................................................... 143Creating Connection Pool Aliases by Copying an Existing Pool Alias............................ 148Editing a Connection Pool Alias......................................................................................149Testing a Connection Pool Alias..................................................................................... 149Deleting a Connection Pool Alias....................................................................................149

Managing Driver Aliases.........................................................................................................150Creating Database Driver Alias Definitions..................................................................... 150Editing Database Driver Aliases......................................................................................150Deleting Database Driver Aliases................................................................................... 151

Configuring Ports.........................................................................................................................153About Ports............................................................................................................................. 154

Available Port Types........................................................................................................154

MTable of Contents

webMethods Integration Server Administrator’s Guide Version 9.8 7

Default Ports....................................................................................................................155About the Port Alias........................................................................................................ 156Package Associations......................................................................................................157

Considerations for Adding Ports.............................................................................................157Reasons to Add Additional Ports.................................................................................... 157Considerations for Configuring Ports.............................................................................. 158

AS/400 Considerations.............................................................................................158Bind Addresses........................................................................................................ 158Prerequisites to Configuring a Port for SSL.............................................................158Port Usage and Security..........................................................................................159

Adding an HTTP Port............................................................................................................. 159Advanced Controls.......................................................................................................... 162

Editing Advanced Controls.......................................................................................162Adding an HTTPS Port...........................................................................................................164Adding a File Polling Port.......................................................................................................169Adding an FTPS Port............................................................................................................. 174Adding an FTP Port................................................................................................................179Adding an E-Mail Port............................................................................................................ 181

Security Considerations for E-Mail Ports........................................................................ 187Adding an HTTP Diagnostic Port........................................................................................... 188Adding an HTTPS Diagnostic Port.........................................................................................192Suspending an HTTP/HTTPS Port.........................................................................................197Resuming an HTTP/HTTPS Port........................................................................................... 198Testing for HTTPS Requests..................................................................................................198Using an FTP/FTPS Port Range............................................................................................198

Specifying an FTP/FTPS Port Range............................................................................. 199About the Primary Port...........................................................................................................200

Changing the Primary Port..............................................................................................200Deleting a Port........................................................................................................................201Editing a Port..........................................................................................................................201About Enabling/Disabling a Port.............................................................................................202

Disabling a Port...............................................................................................................202Enabling a Port................................................................................................................202

Configuring How Ports Handle Client Certificates..................................................................203Adding a Security Provider.....................................................................................................203

Setting Up the Server Log.......................................................................................................... 205Overview................................................................................................................................. 206Specifying Amount and Type of Information to Include in the Server Log..............................207

Logging Levels................................................................................................................ 208Specifying Whether to Queue Server Log Entries................................................................. 209Overriding Logging Level and Server Log Location for a Session......................................... 210Changing the Default Server Log Location............................................................................ 212Sending Messages About Critical Issues to E-mail Addresses..............................................212Performing Additional Processing on Log Entries..................................................................214

MTable of Contents

webMethods Integration Server Administrator’s Guide Version 9.8 8

Viewing the Server Log.......................................................................................................... 214Using an Alternative Server Log Entry Format............................................................... 215

Changing the Log Displays.................................................................................................... 216Specifying the Date and Time Format to Use in Log Entries..........................................216Displaying Logged Data in Different Languages.............................................................216Changing the Display Permanently for All Logs............................................................. 217Changing the Display Temporarily for the Server Log.................................................... 218

Globalization........................................................................................................................... 218

Configuring Integration Server for webMethods Messaging.................................................. 219Overview................................................................................................................................. 220Working with Messaging Connection Aliases.........................................................................220

Predefined Messaging Connection Aliases.....................................................................221Creating a Broker Connection Alias................................................................................222Creating a Universal Messaging Connection Alias......................................................... 225Editing a Messaging Connection Alias............................................................................230Enabling a Messaging Connection Alias.........................................................................231About Disabling a Message Connection Alias................................................................ 232

Disabling a Messaging Connection Alias.................................................................233Messaging Connection Alias Status................................................................................234Specifying the Default Messaging Connection Alias.......................................................235Deleting a Messaging Connection Alias......................................................................... 236

Authenticating Connections to the Universal Messaging Server............................................236Configuring Integration Server to Connect to an SSL-Enabled Port on UniversalMessaging...............................................................................................................................239

Configuring One-Way SSL with Universal Messaging.................................................... 239Configuring Two-Way SSL with Universal Messaging.................................................... 240

Specifying the Keep-Alive Mode for the Broker Connection.................................................. 241Setting Server Configuration Parameters for Keep-Alive Mode...................................... 242Normal Mode................................................................................................................... 242Listen Only Mode............................................................................................................ 243Disabled........................................................................................................................... 243

Synchronizing Broker Clients When the Primary Port for Integration Server Changes.......... 244Configuring Document Stores................................................................................................ 244

Configuring the Default Document Store........................................................................ 245About the Trigger Document Store................................................................................. 247

Configuring the Trigger Document Store................................................................. 247Maintaining Inbound Document History for Received Documents.................................. 248Enabling Inbound Client-Side Queuing........................................................................... 249About the Outbound Document Store.............................................................................249

Configuring the Rate at which Integration Server Drains the Outbound DocumentStore......................................................................................................................... 250Setting the Capacity of the Outbound Document Store...........................................251

Associating a User Account with webMethods Messaging Trigger Services.................. 251Specifying a User Account for Invoking webMethods Messaging TriggerServices.................................................................................................................... 252

MTable of Contents

webMethods Integration Server Administrator’s Guide Version 9.8 9

Load Balancing with a Non-Clustered Group of Integration Servers......................................252Important Considerations.................................................................................................253

Configuring Integration Server for JMS Messaging.................................................................255Overview................................................................................................................................. 256Working with JNDI Providers..................................................................................................256

Predefined JNDI Provider Aliases...................................................................................256Creating a JNDI Provider Alias....................................................................................... 257Editing a JNDI Provider Alias..........................................................................................259Deleting a JNDI Provider Alias........................................................................................260Creating a JNDI Provider Failover List........................................................................... 260Performing a Test Lookup for a JNDI Provider............................................................... 261JNDI Provider Cache and Timeout Behavior for Administered Objects.......................... 261

Working with JMS Connection Aliases...................................................................................262Connecting to webMethods Broker with the Native webMethods API............................ 262Predefined JMS Connection Aliases...............................................................................262Creating a JMS Connection Alias................................................................................... 263

Allowing Destinations to be Managed through the JMS Connection Alias andDesigner................................................................................................................... 273Allowing Multiple Connections for a JMS Connection Alias.....................................273

About the Connection Client ID........................................................................ 274Configuring Producer Caching for Sending JMS Messages.................................... 275Configuring Automatic Retry when Sending JMS Messages Using the pub.jms:sendService......................................................................................................................277

About Retrying the pub.jms:send Service when webMethods UniversalMessaging Is the JMS Provider........................................................................279

Editing a JMS Connection Alias......................................................................................280Enabling and Disabling a JMS Connection Alias............................................................280Deleting a JMS Connection Alias....................................................................................281Specifying a Connection Monitoring Period.................................................................... 281Specifying a Retry Interval for Failed Connections......................................................... 281Specifying a Keep-Alive Interval..................................................................................... 282

Creating Administered Objects...............................................................................................282Monitoring a Connection Factory Object for Changes........................................................... 282

Polling for Changes.........................................................................................................283Registering an Event Listener......................................................................................... 284How Integration Server Updates the Connection............................................................284Configuring Integration Server to Monitor a Connection Factory Object.........................285

Using SSL with JMS...............................................................................................................287Storing SSL Information for JMS.................................................................................... 287

Supported JMS Providers.......................................................................................................288About Using webMethods Universal Messaging as the JMS Provider............................289

Adding JMS Provider Client Libraries to Integration Server Classpath.................................. 291Working with Universal Messaging Version 9.9, 9.10, or 9.12........................................ 295

Adding Client Libraries for Universal Messaging Version 9.9, 9.10, or 9.12.............295

MTable of Contents

webMethods Integration Server Administrator’s Guide Version 9.8 10

Configuring Endpoint Aliases for Web Services......................................................................297Overview................................................................................................................................. 298Creating an Endpoint Alias for a Provider Web Service Descriptor for Use with HTTP/S.......299Creating an Endpoint Alias for a Consumer Web Service Descriptor for Use with HTTP/S... 304Creating an Endpoint Alias for Message Addressing for Use with HTTP/S........................... 315Creating an Endpoint Alias for a Provider Web Service Descriptor for Use with JMS............323Creating an Endpoint Alias for a Consumer Web Service Descriptor for Use with JMS.........329Creating an Endpoint Alias for Message Addressing for Use with JMS.................................337Timestamps in the WS-Security Header................................................................................ 344

Configuring Reliable Messaging in Integration Server............................................................345Overview of Reliable Messaging............................................................................................ 346

Understanding Reliable Messaging Terminology............................................................ 346Using Reliable Messaging in Integration Server.................................................................... 347

Persistent Storage Support for Reliable Messaging Data...............................................348Limitations When Using Reliable Messaging in Integration Server.................................349

Configuring Reliable Messaging in Integration Server........................................................... 349Reliable Messaging Sequence Reports................................................................................. 352

Client and Server Sequences......................................................................................... 352Viewing Reliable Messaging Sequence Reports.............................................................353

Closing a Sequence............................................................................................................... 354Terminating a Sequence.........................................................................................................354Sending an Acknowledgement Request................................................................................ 355

Configuring Kerberos in Integration Server............................................................................. 357Overview................................................................................................................................. 358

Understanding Kerberos Terminology............................................................................. 358Prerequisites to Configuring Kerberos............................................................................ 359

Limitations When Using Kerberos Authentication in Integration Server................................. 359Configuring Kerberos in Integration Server............................................................................359

Order of Precedence for Client Principal Name and Password...................................... 360Troubleshooting Kerberos Configuration................................................................................ 361

Setting Up HTTP URL Aliases for Services.............................................................................. 363Overview................................................................................................................................. 364Partial Matching of URL Aliases............................................................................................ 364Displaying HTTP URL Aliases................................................................................................365

HTTP URL Alias List....................................................................................................... 365Portability of Aliases........................................................................................................ 366

Creating an HTTP URL Alias................................................................................................. 366Deleting a URL Alias.............................................................................................................. 367

Configuring Integration Server to Connect to an SFTP Server...............................................369Overview of SFTP.................................................................................................................. 370Creating an SFTP Server Alias..............................................................................................370

Editing an SFTP Server Alias......................................................................................... 371

MTable of Contents

webMethods Integration Server Administrator’s Guide Version 9.8 11

Creating an SFTP User Alias.................................................................................................372Editing an SFTP User Alias............................................................................................ 375Testing the Connection to the SFTP Server................................................................... 375

Securing Communications with the Server.............................................................................. 377Overview................................................................................................................................. 378Anatomy of an Integration Server SSL Connection............................................................... 378

Integration Server and SSL Connection Type.................................................................378Integration Server as an SSL Server.............................................................................. 379Integration Server as an SSL Client............................................................................... 379

Roadmap for Configuring SSL............................................................................................... 380Creating Integration Server Keys and Certificates.......................................................... 381Creating a Keystore and Truststore................................................................................ 382Obtaining the Certificates and Keys of the Partner Application...................................... 382Configuring an HTTPS or FTPS Port..............................................................................382

Keystores and Truststores......................................................................................................383Keystore File....................................................................................................................383

Keystore File Formats.............................................................................................. 383HSM-Based Keystores............................................................................................. 383Creating a Keystore................................................................................................. 384

Truststore File..................................................................................................................384Truststore File Formats............................................................................................ 384

How Integration Server Uses a Keystore and Truststore................................................384Protecting Keystore and Truststore Files........................................................................ 385Keystore, Truststore, and Key Aliases............................................................................ 385

Default Keystore and Truststore Aliases..................................................................386Creating Keystore Aliases........................................................................................386Creating Truststore Aliases...................................................................................... 388

Configuring Server-Side SSL Settings................................................................................... 390Specifying the Integration Server SSL Authentication Credentials................................. 390

Controlling Server SSL Security Level by Port...................................................................... 391Usage of CA Certificates: Technical Considerations..............................................................391

Handling Expired CA Certificates....................................................................................391Customizing Usage of the Trusted Certificates Directory................................................392

WS-Security and Integration Server.......................................................................................392

Controlling Access to Resources.............................................................................................. 395Overview................................................................................................................................. 396Controlling Access to Resources by Port...............................................................................396

Restricting IP Addresses that Can Connect to a Port.....................................................397Controlling IP Access to All Ports (Globally)............................................................398

Allow Inbound Connections from Specified Hosts (Deny All Others)................ 398Deny Inbound Connections from Specified Hosts (Allow All Others)................ 399

Allow Inbound Requests from Specified Hosts (Deny All Others)............................400Deny Inbound Requests from Specified Hosts (Allow All Others)............................401If You Inadvertently Deny IP Access to All Hosts.................................................... 402

MTable of Contents

webMethods Integration Server Administrator’s Guide Version 9.8 12

Resetting the Global Setting IP Access Setting................................................402Resetting the IP Access Setting for an Individual Port..................................... 403

Restricting the Services or Web Service Descriptors Available from a Port....................403Allow Access to Specified Services (Deny All Others)............................................ 404Deny Access to Specified Services (Allow All Others)............................................ 406

Resetting a Port to the Default Access.............................................................407Controlling the Use of Directives............................................................................................407Controlling Access to Resources with ACLs..........................................................................409

About ACLs..................................................................................................................... 409Package Replication.................................................................................................412Implicit and Explicit Protection................................................................................. 412Users that Belong to More than One Group............................................................412

Predefined ACLs............................................................................................................. 413When Does the Server Perform ACL Checking?............................................................414Creating ACLs................................................................................................................. 414Allowing or Denying Group Access to ACLs...................................................................415Deleting ACLs..................................................................................................................415Default Settings and Inheritance..................................................................................... 416

What Happens When You Change Existing ACL Assignments............................... 417Assigning ACLs to Folders, Services, and Other Elements............................................417Removing an ACL from a Folder or Service...................................................................418Assigning ACLs to Files the Server Can Serve.............................................................. 419

Rules for Using .access Files...................................................................................419Removing ACL Protection from a File............................................................................ 420

Authenticating Clients.................................................................................................................421Overview................................................................................................................................. 422Basic Authentication............................................................................................................... 422Digest Authentication..............................................................................................................423Client Certificates....................................................................................................................424

Checklist for Using Client Certificates.............................................................................424Certificate Mapping..........................................................................................................424

Ports and Certificate Mappings................................................................................425Importing a Certificate (Client or CA Signing Certificate) and Mapping It to aUser.......................................................................................................................... 425Changing a Certificate Mapping...............................................................................426

Client Certificates and Port Configuration.......................................................................427HTTPS Ports............................................................................................................ 427FTPS Ports...............................................................................................................428

Using Multiple Client Certificates............................................................................................429Checklist for Presenting Multiple Client Certificates........................................................430Importing Certificates.......................................................................................................430Setting Up a Remote Server Alias..................................................................................430Coding Your Flow Services............................................................................................. 431

Client Authentication and Access Control.............................................................................. 431

MTable of Contents

webMethods Integration Server Administrator’s Guide Version 9.8 13

Accessing Integration Server Data through My webMethods................................................ 432Configuring the MWS Single Sign-On Resource Setting................................................ 432

Customizing Authentication Using JAAS................................................................................. 435Overview................................................................................................................................. 436Using JAAS with Integration Server....................................................................................... 436JAAS Configuration File......................................................................................................... 436

Pre-installed Login Modules............................................................................................ 437X509ValidatorModule.......................................................................................................438

Pluggable Authentication Modules (PAMs)............................................................................ 438Writing a Custom JAAS Login Module for Integration Server................................................ 439

Extend SagAbstractLoginModule.................................................................................... 439Implement Commit()........................................................................................................ 440Place the JAR File in the Integration Server Classpath..................................................440Modify the JAAS Configuration File................................................................................ 440

JAAS Custom Login Module Example................................................................................... 441JAAS Login Module for Integration Server: Sample Code..............................................441JAAS Custom Login Module: Code Explanation.............................................................442JAAS Configuration File: Sample Module.......................................................................443

Master Passwords and Outbound Passwords......................................................................... 445Overview................................................................................................................................. 446Managing Outbound Passwords............................................................................................ 447Backing Up Outbound Password and Master Password Files...............................................448Changing the Master Password............................................................................................. 448Changing the Expiration Interval for the Master Password.................................................... 449About the configPassman.cnf File..........................................................................................449Working with Outbound Password Settings........................................................................... 450

Controlling Name and Location of Outbound Password File.......................................... 450Controlling Encryption of Outbound Password File.........................................................451

Working with Master Password Settings................................................................................451Storing the Master Password in a File............................................................................451Prompting for the Master Password at Server Initialization............................................ 452

What to Do if You Lose or Forget Your Master Password..................................................... 453When Problems Exist with the Master Password or Outbound Passwords at Startup........... 454

Determining Whether You Can Restore the Passwords................................................. 454Restoring the Master Password and Outbound Password Files.....................................455Resetting the Master Password and Outbound Passwords............................................456

E-mail Listeners and Package Replication.............................................................................457

Securing Integration Server with CSRF Guard.........................................................................459What is CSRF?.......................................................................................................................460How Does Integration Server Prevent CSRF Attacks?.......................................................... 460Understanding CSRF Guard Terminology..............................................................................460Configuring CSRF Guard in Integration Server......................................................................462Limitations when Configuring CSRF Guard in Integration Server.......................................... 464

MTable of Contents

webMethods Integration Server Administrator’s Guide Version 9.8 14

Configuring webMethods Enterprise Gateway......................................................................... 467Overview................................................................................................................................. 468How Enterprise Gateway Works............................................................................................ 468

Enterprise Gateway Ports............................................................................................... 469Enterprise Gateway Rules and Alerts............................................................................. 470

About Enterprise Gateway Rules.............................................................................470About Enterprise Gateway Alerts.............................................................................471

Version Interoperability Between Enterprise Gateway Server and Internal Server.................472Advantages of Enterprise Gateway over Traditional Third-Party Proxy Servers.................... 473About Denial of Service Protection........................................................................................ 474

About Trusted IP Addresses........................................................................................... 474About Mobile Application Protection.......................................................................................475About Mobile Data Synchronization....................................................................................... 475About SQL Injection Protection.............................................................................................. 476About Antivirus Scan Filter.....................................................................................................476Clustering in the Enterprise Gateway Configuration.............................................................. 477Setting Up an Enterprise Gateway.........................................................................................478Configuring the Enterprise Gateway Ports.............................................................................480

Deleting Enterprise Gateway External and Registration Ports........................................485Connecting Your Internal Server to an Enterprise Gateway Server....................................... 485Viewing Connections to the Enterprise Gateway Registration Port........................................489Performing Client Authentication on Enterprise Gateway Server...........................................490Working with Enterprise Gateway Rules................................................................................491

Creating an Enterprise Gateway Rule............................................................................ 491Enabling an Enterprise Gateway Rule............................................................................ 495Disabling an Enterprise Gateway Rule........................................................................... 496Editing an Enterprise Gateway Rule............................................................................... 496Copying an Enterprise Gateway Rule.............................................................................496Changing the Priority of an Enterprise Gateway Rule.................................................... 497Deleting an Enterprise Gateway Rule.............................................................................497

Specifying Alert Options......................................................................................................... 498Specifying Default Alert Options..................................................................................... 498Specifying Rule-Specific Alert Options............................................................................499

Preventing Denial of Service Attacks..................................................................................... 500Limiting Requests Globally..............................................................................................500Limiting Requests by IP Address....................................................................................501

Controlling Use of Mobile Applications...................................................................................502Frequently Asked Questions about Enterprise Gateway........................................................504

Configuring OAuth.......................................................................................................................509What Is OAuth?...................................................................................................................... 510Using OAuth with Integration Server......................................................................................511

Integration Server as an OAuth Client............................................................................ 511Integration Server as an Authorization Server................................................................ 511Integration Server as a Resource Server........................................................................511

MTable of Contents

webMethods Integration Server Administrator’s Guide Version 9.8 15

Authorization Grant Types Supported by Integration Server..................................................512Authorization Code Grant................................................................................................512Implicit Grant................................................................................................................... 514

The Integration Server OAuth Services................................................................................. 516Important Considerations for Using OAuth Features............................................................. 517Configuring the Authorization Server..................................................................................... 517

Configuring OAuth Settings.............................................................................................518Defining Clients............................................................................................................... 520

Registering Clients................................................................................................... 520Enabling and Disabling Clients................................................................................ 523Editing Clients.......................................................................................................... 524Deleting Clients........................................................................................................ 524

Defining Scopes.............................................................................................................. 524Adding a Scope........................................................................................................525Editing Scopes......................................................................................................... 525Deleting Scopes....................................................................................................... 526

Associating Scopes and Clients......................................................................................526Adding Associations Between Clients and Scopes..................................................527Removing Client and Scope Associations............................................................... 528Viewing Associations Between Clients and Scopes................................................ 529

Viewing and Deleting Tokens.......................................................................................... 530Viewing Tokens.........................................................................................................530Deleting Tokens........................................................................................................530

Customizing the Approval Page......................................................................................531About Using Integration Server as the Resource Server....................................................... 531

Configuring a Central User Directory or LDAP........................................................................ 533Before You Begin....................................................................................................................534Overview of How Integration Server Works with Externally Defined Users and Groups........ 534

How the Server Uses Externally Defined Users and Groups..........................................535When the Server Accesses Externally Defined Information............................................535How Integration Server Authenticates Externally Defined Clients...................................535

Configuring Central User Management..................................................................................536Requirements for Central User Management................................................................. 537Considerations for My webMethods Server Query Roles............................................... 537

Overview of Using LDAP........................................................................................................538About LDAP and Caching............................................................................................... 538

Configuring the Server to Use LDAP..................................................................................... 539Defining an LDAP Directory to Integration Server.......................................................... 540Mapping an LDAP User's Access to ACLs..................................................................... 545Stopping Use of an LDAP as an External Directory....................................................... 545

Considerations for User Accounts and Groups......................................................................545About Keeping Internal and External User Accounts and Group Names Unique............546About User Groups and Package Replication................................................................ 546

About Granting Administrator Privileges to External Users....................................................547

MTable of Contents

webMethods Integration Server Administrator’s Guide Version 9.8 16

Granting Administrator Privileges to an Externally Defined User....................................548Granting Developer Privileges to External Users...................................................................548Granting Access to Services and Files to External Users......................................................549

Managing Packages.....................................................................................................................551Using Packages......................................................................................................................552

Predefined Packages.......................................................................................................552The Package Repository................................................................................................. 556Sample Package............................................................................................................. 556

How the Server Stores Package Information.........................................................................556Manifest File.................................................................................................................... 558

Finding Information about Your Packages............................................................................. 559Viewing the Packages that Reside on Your Server........................................................ 560

Filtering the List of Packages...................................................................................561Refining the Filtered Package List........................................................................... 562Determining Whether the Server Successfully Loaded the Package.......................562Determining Whether the Package Is Enabled or Disabled.....................................563

Displaying Information about a Package........................................................................ 563Package Information.................................................................................................564

Displaying Information about Services and Folders in a Package.................................. 566Displaying Documentation for a Package....................................................................... 566

Accessing a Web Document for a Package............................................................ 567Working with Packages.......................................................................................................... 567

Creating a Package.........................................................................................................568Activating a Package.......................................................................................................569Reloading a Package...................................................................................................... 569Enabling a Package........................................................................................................ 570Disabling a Package........................................................................................................570Deleting a Package......................................................................................................... 571Recovering a Package.................................................................................................... 571Archiving a Package........................................................................................................572

Copying Packages from One Server to Another....................................................................572Overview of Package Replication................................................................................... 573Version Checking.............................................................................................................577

Who Can Subscribe?............................................................................................... 578Guidelines for Using Package Replication...............................................................579

The Publishing Server..................................................................................................... 579Displaying Subscribers for a Specific Package........................................................580Displaying Subscribers for all Packages..................................................................580Adding Subscribers from a Publishing Server......................................................... 581Updating Subscriber Information..............................................................................582Removing Subscribers for a Package......................................................................583Publishing a Package...............................................................................................584

Creating a Release........................................................................................... 585Sending a Release............................................................................................585

MTable of Contents

webMethods Integration Server Administrator’s Guide Version 9.8 17

Specifying File and Version Information for a Release or Archive.................................. 585The Subscribing Server...................................................................................................589

Displaying Packages to Which Your Server Subscribes.......................................... 590Manually Pulling a Package.....................................................................................590Subscribing to a Package from a Subscribing Server............................................. 591

Requesting a Subscription to a Package from Another Server.........................591Updating Your Subscription Information...................................................................593Canceling a Subscription......................................................................................... 595About Installing Packages Published by Another Server.........................................596

Installing a Package Published by Another Server...........................................596Using a Package Class Loader..............................................................................................598Hot Deployment of Packages.................................................................................................599

How Hot Deployment Works........................................................................................... 599Determining Package Dependencies during Hot Deployment................................. 600

Limitations When Hot Deploying the Packages.............................................................. 600Configuring the Hot Deployment Settings.......................................................................600

Managing Services...................................................................................................................... 603About Services........................................................................................................................604Fully Qualified Service Names............................................................................................... 604

Package Names and Service Names............................................................................. 605HTTP URL Aliases for Services......................................................................................605

Finding Information about Services and Folders....................................................................606Listing Folders and Services...........................................................................................606Displaying Information about a Service.......................................................................... 606

Service Information...................................................................................................607Manually Adding a Service to the Server...............................................................................608Testing Services......................................................................................................................608Canceling and Killing Threads Associated with a Service..................................................... 608

Canceling or Killing a Thread..........................................................................................609Running Services When Packages Are Loaded, Unloaded, or Replicated............................ 610

What Is a Startup Service?............................................................................................. 610What Is a Shutdown Service?.........................................................................................611What Is a Replication Service?.......................................................................................611Guidelines for Using Startup, Shutdown, and Replication Services................................611

Running Services in Response to Specific Events................................................................ 612Managing Global Variables.....................................................................................................612

Creating a Global Variable.............................................................................................. 613Deleting Global Variables................................................................................................ 614

Scheduling Services....................................................................................................................615Overview................................................................................................................................. 616

Tasks Provided by Integration Server............................................................................. 616Scheduling a User Task......................................................................................................... 616Viewing Scheduled User Tasks.............................................................................................. 621

Filtering the List of Scheduled Tasks.............................................................................. 622

MTable of Contents

webMethods Integration Server Administrator’s Guide Version 9.8 18

Updating Scheduled User Tasks............................................................................................ 623Suspending User Tasks..........................................................................................................623

Suspending a Single User Task......................................................................................623Suspending All User Tasks............................................................................................. 624

Resuming Suspended User Tasks......................................................................................... 624Resuming a Suspended User Task.................................................................................624Resuming All Suspended User Tasks.............................................................................625

Canceling a Scheduled User Task......................................................................................... 626Viewing the Scheduled System Tasks................................................................................... 626Simple Repeating Option........................................................................................................626Complex Repeating Option.................................................................................................... 628Target Node Options...............................................................................................................632

Tasks in a Clustered Environment.................................................................................. 633How Transitioning to or from Daylight Savings Time Affects Scheduled Tasks......................634

Caching Service Results.............................................................................................................635What Is Caching?................................................................................................................... 636When Are Cached Results Returned?................................................................................... 636Resetting the Cache...............................................................................................................638

Resetting the Cache for All Services.............................................................................. 638Resetting the Cache for a Specific Service.................................................................... 638

Monitoring Service Cache Usage...........................................................................................638

Configuring Guaranteed Delivery...............................................................................................641About Guaranteed Delivery.................................................................................................... 642Configuring the Server for Guaranteed Delivery.................................................................... 643

Settings Shared by Both Inbound and Outbound Transactions...................................... 643Settings for Inbound Transactions...................................................................................644Settings for Outbound Transactions................................................................................645Specifying an E-Mail Address and SMTP Server for Error Messages............................ 646Using Guaranteed Delivery with Multiple Servers that Share an ISInternal Database.... 647

Administering Guaranteed Delivery........................................................................................647Shutting Down Guaranteed Delivery...............................................................................647Reinitializing Guaranteed Delivery.................................................................................. 648

Reinitializing Guaranteed Delivery for Inbound Transactions.................................. 648Reinitializing Guaranteed Delivery for Outbound Transactions................................648

Configuring Ehcache on Integration Server............................................................................. 651What is Ehcache?.................................................................................................................. 652Caching Configurations.......................................................................................................... 652

On-Heap Cache...............................................................................................................653Local Disk Store.............................................................................................................. 653BigMemory.......................................................................................................................654Terracotta Server Array................................................................................................... 655

Understanding Caches and Cache Managers....................................................................... 657System Caches............................................................................................................... 658

MTable of Contents

webMethods Integration Server Administrator’s Guide Version 9.8 19

Cache Manager Configuration Files.......................................................................................658Specifying the Parameters for a Cache.......................................................................... 659

Dynamic vs. Non-Dynamic Cache Parameters........................................................659Installing, Viewing, and Changing the Terracotta License......................................................660

Determining if You Have a Terracotta License................................................................661Adding a Terracotta License............................................................................................661

Configuring an On-Heap Cache............................................................................................. 662Considerations for Configuring On-Heap Cache.............................................................662

Configuring a BigMemory Cache........................................................................................... 663Allocating Direct Memory Space to Integration Server................................................... 665Considerations for Configuring BigMemoryCache.......................................................... 665

Configuring a Distributed Cache............................................................................................ 667Configuring tc-config.xml on the Terracotta Server Array............................................... 669Considerations for Configuring a Distributed Cache....................................................... 670Cache-Wide and Client-Specific Parameters for a Distributed Cache............................ 671

Cache-Wide Parameters.......................................................................................... 671Client-Specific Parameters....................................................................................... 672

The Rejoin Behavior of a Distributed Cache...................................................................673The Nonstop Behavior of a Distributed Cache............................................................... 674

Making a Cache Searchable.................................................................................................. 675Defining Attributes........................................................................................................... 676

Working with Cache Managers.............................................................................................. 676Creating a Cache Manager........