Broker Admin Guide

webMethods Broker
Administrator’s Guide
VERSION 6.5
webMethods, Inc.
South Tower
3877 Fairfax Ridge Road
Fairfax, VA 22030
USA
703.460.2500
http://www.webmethods.com
webMethods Administrator, webMethods Broker, webMethods Dashboard, webMethods Developer, webMethods Fabric, webMethods Glue, webMethods
Installer, webMethods Integration Server, webMethods Mainframe, webMethods Manager, webMethods Mobile, webMethods Modeler, webMethods
Monitor, webMethods Optimize, webMethods Portal, webMethods Trading Networks, and webMethods Workflow are trademarks of webMethods, Inc.
webMethods and the webMethods logo are registered trademarks of webMethods, Inc.
Acrobat, Adobe, and Reader are registered trademarks of Adobe Systems Incorporated. Amdocs is a registered trademark, and ClarifyCRM is a trademark of
Amdocs Inc. Ariba is a registered trademark of Ariba, Inc. BEA and BEA WebLogic Server are registered trademarks, and BEA WebLogic Platform is a
trademark of BEA Systems, Inc. BMC Software and PATROL are registered trademarks of BMC Software, Inc. BroadVision is a registered trademark of
BroadVision, Inc. ChemeStandards and CIDX are registered trademarks of Chemical Industry Data Exchange. Unicenter is a trademark of Computer
Associates International, Inc. PopChart is a registered trademark of CORDA Technologies, Inc. Kenan and Arbor are registered trademarks of CSG Software,
Incorporated. SNAP-IX and Data Connection are registered trademarks of Data Connection Corporation. DataDirect, DataDirect Connect, and SequeLink are
registered trademarks of DataDirect Technologies Corp. D & B and D-U-N-S are registered trademarks of Dun & Broadstreet, Inc. Entrust is a registered
trademark of Entrust, Inc. Hewlett-Packard, HP, HP-UX, and OpenView are trademarks of Hewlett-Packard Company. i2 is a registered trademark of i2
Technologies, Inc. AIX, AS/400, CICS, DB2, Domino, IBM, Infoprint, Lotus, Lotus Notes, MQSeries, OS/390, OS/400, RACF, RS/6000, S/390, System/390, VTAM,
z/OS, and WebSphere are registered trademarks; and Informix, SQL/400, Communications System for Windows NT, IMS, MVS, SQL/DS, and Universal
Database are trademarks of IBM Corporation. InnoDB is a trademark of Innobase Oy. JBoss is a registered trademark, and JBoss Group is a trademark of JBoss
Inc. JD Edwards is a registered trademark of J.D. Edwards & Company and OneWorld is a registered trademark of J.D. Edwards World Source Company.
Linux is a registered trademark of Linus Torvalds. X Window System is a trademark of the X.org Foundation. MetaSolv is a registered trademark of Metasolv
Software, Inc. ActiveX, Microsoft, Outlook, Visual Basic, Windows, and Windows NT are registered trademarks; and SQL Server is a trademark of Microsoft
Corporation. MySQL is a registered trademark of MySQL AB, Ltd. Teradata is a registered trademark of NCR International, Inc. Netscape is a registered
trademark of Netscape Communications Corporation. ServletExec is a registered trademark, and New Atlanta is a trademark of New Atlanta
Communications, LLC. CORBA is a registered trademark of Object Management Group, Inc. UNIX is a registered trademark of X/Open Company Ltd. Oracle
is a registered trademark of Oracle International Corporation. PeopleSoft and Vantive are registered trademarks, and PeopleSoft Pure Internet Architecture
and WorldSoftware are trademarks of PeopleSoft, Inc. Infranet and Portal are trademarks of Portal Software, Inc. RosettaNet is a trademark of RosettaNet, a
non-profit organization. SAP and R/3 are registered trademarks of SAP AG. Siebel is a registered trademark of Siebel Systems, Inc. SPARC is a registered
trademark, and SPARCStation is a trademark of SPARC International, Inc. SSA Global and SSA Baan are trademarks of SSA Global Technologies, Inc. EJB,
Enterprise JavaBeans, Java, JavaServer, JDBC, JSP, J2EE, Solaris, and Sun Microsystems are registered trademarks; and Java Naming and Directory Interface,
SOAP with Attachments API for Java, JavaServer Pages and SunSoft are trademarks of Sun Microsystems, Inc. SWIFT and SWIFTNet are registered
trademarks of Society for Worldwide Interbank Financial Telecommunication SCRL. Sybase is a registered trademark of Sybase, Inc. UCCnet and
eBusinessReady are registered trademarks of Uniform Code Council, Inc. Verisign is a registered trademark of Verisign, Inc. VERITAS is a registered
trademark of VERITAS Operating Corporation, and VERITAS Software and VERITAS Cluster Server are trademarks of VERITAS Software Corporation. W3C
is a registered trademark of Massachusetts Institute of Technology.
All other marks are the property of their respective owners.
Copyright © 2005 by webMethods, Inc. All rights reserved, including the right of reproduction in whole or in part in any form.
Document ID: BR-AG-65-20050615

Contents
About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Part I. Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Chapter 1. Overview of webMethods Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
webMethods Broker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Broker Server Host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Client State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
webMethods Broker Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Broker Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Command Line Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
webMethods JMS Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Setting Up a webMethods Broker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Chapter 2. Using the webMethods Broker Management Tools . . . . . . . . . . . . . . . . . . . . . 25

Starting the webMethods Broker Management Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Logging On to Broker Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Quick Tour of Broker Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Viewing Broker Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Notes on Using Broker Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Customizing the View of Broker Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Sorting Information in Broker Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Updating Information on Broker Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Setting Up Broker Administrator Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Viewing and Changing Connection Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Viewing and Changing Client Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Viewing and Changing Identity Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Basic Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Displaying webMethods Broker Server Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Displaying Broker Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
The Brokers Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
webMethods Broker Administrator’s Guide Version 6.5 3

Contents
Part II. Broker Server and Broker Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Chapter 3. Managing webMethods Broker Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Managing the webMethods Broker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Creating a webMethods Broker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Adding a Broker Server to Broker Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Adding Multiple Broker Servers to Broker Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Creating a Broker Server List File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Importing a Broker Server List File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Removing a Broker Server from the Broker Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Monitoring webMethods Broker Server Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Updating the webMethods Broker Software License Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Logging webMethods Broker Server Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Configuring Log Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Using the Broker System Log Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Copying webMethods Broker Server and Broker Information . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Methods of Copying Broker Server and Broker Information . . . . . . . . . . . . . . . . . . . . . . . . 54
Configuring webMethods Broker Servers from the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Using Separate Storage Sessions and Online Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Configuring the Storage Cache Size for a webMethods Broker Server . . . . . . . . . . . . . . . . . . . . . . . 56
Configuring webMethods Broker to Use Asynchronous Write Mode . . . . . . . . . . . . . . . . . . . . . . . . . 57
Configuring webMethods Broker Monitor Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Stopping and Starting a webMethods Broker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Shutting Down the webMethods Broker System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
webMethods Broker Server Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Shutting Down and Restarting a Broker Server on Solaris, HP-UX, and Windows Platform 63
Chapter 4. Managing Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Managing Individual Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Creating New Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Assigning Default Status to a Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Enabling Document Type Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Setting Up Your webMethods Broker for Higher Performance . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Improving Your Broker Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
webMethods Broker Document Sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Broker's Guaranteed Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Deleting Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Name Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Uninstalling Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Deploying Additional Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Methods of Copying Broker Server and Broker Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
4 webMethods Broker Administrator’s Guide Version 6.5

Chapter 5. Copying, Saving, and Restoring Configuration Data . . . . . . . . . . . . . . . . . . . . 73
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Copying Broker and Broker Server Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Using the Clipboard Feature of the Broker Administrator to Copy . . . . . . . . . . . . . . . . . . . . . . . 77
Using Broker Command Line Tools to Copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Using the ADL Export/Import Feature of the Broker Administrator to Copy . . . . . . . . . . . . . . . . 78
File Formats for Saving ADL Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Saving and Restoring System Configuration Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Backing Up and Restoring System Configuration Using ADL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Backing Up By Exporting System Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Exporting Broker Server Configuration Using ADL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Exporting Broker Server Configuration from the Command Line . . . . . . . . . . . . . . . . . . . . 83
Restoring System Configuration Through ADL Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Backing Up and Restoring System Configuration Data Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Backing Up System Configuration Data Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Backing Up from the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Restoring System Configuration Using the server_conf_restore Command Line Tool . . . . . . . . 87
Backing up and Restoring Combined Broker Server Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Backing up Broker SSL Certificate Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Part III. Client Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Chapter 6. Managing Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Understanding Client Group Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Life Cycle Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Client Queue Storage Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Maximum Storage File Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Client Queue Storage Versus Document Type Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Displaying Client Group Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Creating and Configuring a Client Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Creating a Client Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Assigning “Can Publish” and “Can Subscribe” Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Adding “Can Publish” and “Can Subscribe” Permission . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Removing Can Publish and Can Subscribe Permission . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Assigning Log Publish and Log Acknowledge Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Changing a Client Group Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Setting the Client Group Encryption Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Deleting a Client Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Contents
Chapter 7. Managing Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
About Managing Document Types in a Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Displaying the Document Types in a Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Editing Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Document Type Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Document Type Storage Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Document Time to Live . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Document Type Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Data Field Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Displaying Subscription Filter Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Chapter 8. Managing Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Viewing Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Displaying Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Client Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Displaying Broker Client Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Displaying Documents in a Client Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Displaying the Subscriptions Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Displaying the Sessions Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Managing Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Managing Broker Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Disconnecting Broker Client Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Managing Client Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Clearing Documents in a Client Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Set Up Logging for Broker Clients and JMS Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Monitoring Broker Client Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Displaying Broker Client Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Controlling Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Removing a Broker Client Subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Disconnecting a Broker Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Deleting a Broker Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Part IV. webMethods Broker Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Chapter 9. Monitoring and Managing Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Using Transaction Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Viewing Running Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Setting the Timeout Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Setting the Recover Mode for XA Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Manually Performing a Commit or Roll Back . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Viewing and Purging Lost Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Chapter 10. Territories and Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Rules Concerning Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Unique Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Managing Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Creating a Territory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Viewing Territory Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Joining a Territory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Leaving a Territory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Territory Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Using Broker Remote Publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Displaying Gateway Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Displaying the Shared Document Type List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Pausing or Resuming a Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Static Gateway Forwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Preventing Firewall Disconnections of Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Configuring a Gateway if You Control Both Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Creating the Gateway (Both Brokers) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Configuring the Shared Document Type List (Both Brokers) . . . . . . . . . . . . . . . . . . . . . . . 155
Configuring a Gateway If You Control One Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Creating the Gateway (One Broker) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Configuring the Shared Document Type List (One Broker) . . . . . . . . . . . . . . . . . . . . . . . . . 158
Removing a Shared Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Removing a Territory Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Using Gateway Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Filtering Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Filter Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Filter Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Chapter 11. Managing Broker Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

Security Using Secure Sockets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
A Brief Description of SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Public Key Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Modes of Secure Sockets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Trusted Roots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Distinguished Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Using webMethods Broker with SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Access Control Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Administrative Access to webMethods Broker Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Administrative Access to Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Client Access to Broker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Administrative Access to Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Contents
A Roadmap for Implementing SSL Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

Configuring the webMethods Broker Server for SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Determining If You Have an SSL License Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Preparing the Certificate File for the Broker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Configuring Broker Administrator for SSL Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Enabling SSL for the webMethods Broker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Setting Up Access Control Lists for the webMethods Broker Server . . . . . . . . . . . . . . . . . 176
Setting Up Client Group Access Control Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Using SSL for Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Using SSL Across Territory Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Enabling SSL If You Control Both Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Enabling SSL If You Control One Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Gateway SSL and Territory SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Creating and Managing SSL Certificate Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Uploading Certificate Files Using the Broker Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Using the Certificate Manager Program (awcert) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Installing Trusted Roots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Generating Key Pairs and Certificate Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Installing Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Additional Operations for Trusted Roots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Listing Trusted Roots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Removing Trusted Roots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Additional Operations for Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Listing Certificates in the Certificate File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Copying All Certificates in a Certificate File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Exporting a Single Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Changing Certificate Files to an Exportable Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Removing Certificates from a Certificate File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Changing the Certificate File Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Using Distinguished Names with awcert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Certificate Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Working with Firewalls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Using SSL through Firewalls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Using Access Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
User-Based Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
The webMethods Broker Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Client Ownership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
What is an Access Label? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Acquiring an Access Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

How Access Labels Are Used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Source Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Control Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Receipt Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
The Access Label Adapter (ALA) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
ALA Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
The Access Label Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Expiration of Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Broker-to-Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Chapter 12. Configuring Administered Objects with the JMS Administrator . . . . . . . . . . . 205
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Configuration Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Starting the JMS Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Configuring the JNDI Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Uploading a JNDI Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Selecting a Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Creating and Managing JMS Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Administering Queue Connection Factories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Administering Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Administering Topic Connection Factories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Administering Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Part V. Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Appendix A. webMethods Broker Command Line Utilities . . . . . . . . . . . . . . . . . . . . . . . . . 229

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Broker Server Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Broker Server Configuration Storage Backup Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Broker Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
server_conf_backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
server_conf_restore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
server_config add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
server_config create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Creating Separate Storage Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
Creating a Combined Storage Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
server_config delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
server_config help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
server_config list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
server_config remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

Contents
server_config start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

server_config stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
server_config storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
server_config update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
broker_buildall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
broker_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
broker_delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
broker_load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
broker_ping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Pinging a Remote Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
broker_save . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
broker_stop and broker_start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
broker_stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
broker_start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Shutting Down the webMethods Broker Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Shutting Down the webMethods Broker Processes on Solaris . . . . . . . . . . . . . . . . . . . . . . 264
Shutting Down the webMethods Broker Processes on HP-UX . . . . . . . . . . . . . . . . . . . . . . 264
broker_status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Appendix B. Tips and Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

Tips on Using webMethods Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Importing Large ADL Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Increasing the Session Timeout Value for Integration Server . . . . . . . . . . . . . . . . . . . . . . . 268
Importing a Large ADL File Using the broker_load Command Line Utility . . . . . . . . . . . . . 268
Setting Maximum Thread Limit for HP-UX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Working Without a Network Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Working with Multiple Instances of a Single Broker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Adding Multiple Instances of a Broker Server to Broker Administrator . . . . . . . . . . . . . . . . 270
Scaling the webMethods Broker System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
What is the maximum number of Brokers per webMethods Broker Server? . . . . . . . . . . . . 271
What is the maximum number of Brokers per territory? . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
What is the maximum number of Territories per webMethods Broker Server? . . . . . . . . . . 272
What is the maximum number of Broker clients per Broker? . . . . . . . . . . . . . . . . . . . . . . . 272
webMethods Broker Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Glossary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

About This Guide
About This Guide
This guide provides information about how to use the webMethods Broker Administrator
and command line utilities. It describes how to create and manage Brokers on a Broker
Server, set up access permissions, and monitor document traffic through a Broker.
webMethods software needs to be successfully installed before you can use webMethods
Broker Administrator.
webMethods Broker Administrator’s Guide Version 6.5 is designed primarily for the system
administrator who is responsible for configuring and monitoring the webMethods Broker.
This guide assumes you are familiar with the following:
Terminology and basic operations of your operating system (OS)
Basic concepts of webMethods Broker architecture

This guide also assumes that the systems on which you are running the webMethods
Broker software meet or exceed the recommended system requirements outlined in the
webMethods Installation Guide.
Document Conventions
Convention Description
Bold Identifies elements on a screen.
Italic Identifies variable information that you must supply or change based
on your specific situation or environment. Identifies terms the first
time they are defined in text. Also identifies service input and output
variables.
Narrow font Identifies storage locations for services on the webMethods Integration
Server using the convention folder.subfolder:service.
Typewriter Identifies characters and values that you must type exactly or
font messages that the system displays on the console.
UPPERCASE Identifies keyboard keys. Keys that you must press simultaneously are
joined with the “+” symbol.
\ Directory paths use the “\” directory delimiter unless the subject is
UNIX-specific.
[] Optional keywords or values are enclosed in [ ]. Do not type the [ ]
symbols in your own code.

Additional Information
The webMethods Advantage Web site at http://advantage.webmethods.com provides you
with important sources of information about the webMethods Integration Platform:
Troubleshooting Information. webMethods provides troubleshooting information for
many webMethods components in the webMethods Knowledge Base.
Documentation Feedback. To provide documentation feedback to webMethods, go to the
Documentation Feedback Form on the webMethods Bookshelf.
Additional Documentation. All webMethods documentation is available on the
webMethods Bookshelf.

PART I
Getting Started
Overview of webMethods Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Using the webMethods Broker Management Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

CHAPTER 1
Overview of webMethods Broker
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
webMethods Broker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
webMethods Broker Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Setting Up a webMethods Broker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

CHAPTER 1 Overview of webMethods Broker
Overview
This chapter introduces webMethods Broker and describes its components and
management tools for Windows and UNIX systems. The management tools include
webMethods Broker Administrator and the command line utilities.
webMethods Broker Server

The Broker Server is software you install on a machine known as the webMethods Broker
Server Host. The Broker Server mediates requests to and from network information
resources. Client applications publish and subscribe to information in the form of
documents.
The Broker Server manages the flow of documents among clients, Brokers, and various
applications. To do this, the Broker Server automatically routes, queues, and filters
documents. The Broker Server guarantees information delivery over networks that may
have intermittent connectivity, such as dial-up connections. All webMethods Broker
components communicate with a Broker Server, not with each other.
Broker Server Host

The computer on which you install the webMethods Broker software is called the
webMethods Broker Server Host. The name of the Broker Server Host is the name
associated with the computer’s IP address (in most cases, the same as the name of the
computer).
Brokers
Each Broker Server has one or more entities, called Brokers, that reside on it. A Broker is
where the client programs connect, where document types are stored, and where client
queues and subscriptions are monitored and stored. When you install a Broker Server, the
installation program creates one Broker and makes it the default Broker. Using the Broker
Administrator tool, you can change the default status of a Broker, add new Brokers, and
delete existing Brokers.
When a Broker client publishes a document, the Broker determines which Broker clients
have subscribed to that document and places the document in the matching Broker client
queues.
Territories
Brokers can share information about their document type definitions and client groups by
joining a territory. Brokers within the same territory have knowledge of each other’s
document type definitions and client groups. Documents can travel from clients on one
Broker to clients on another Broker in the same territory. Each Broker can reside on a

webMethods Broker Server
different Broker Server, if desired. In addition, territories can be linked by territory

gateways to create larger topologies.
Document Types
Documents are messages that travel over a network from a publisher to a subscriber,
through the Broker. Each document is an instance of a document type. A document type’s
name, which must be unique, is carried by all documents of its type.
Document folders provide a means for grouping document types. A document folder
provides scope for naming document types, allowing a document type in one scope to
have the same base name as a document type in another scope. For example,
Order::Received and Order::Shipped are members of the Order document folder and
Part::Received and Part::Shipped are members of the Part scope.
Each document type has properties associated with it, such as its document folder name,
when it was created, how many times it has been published and retrieved by Broker
clients, and the number of subscriptions.
Note:
The maximum size of any single document operation is 1GB with a transaction size
of 1GB.
The maximum number of document types that a Broker can support is 65533.
Broker Clients
A Broker client is an object that is used by client programs. A Broker client is a handle that
is created and used by client programs. It represents a connection to a particular Broker.
Client programs may use one or more Broker clients.
Client State
A Broker client has a client state. The client state is the information about a Broker client
that the Broker maintains. This information includes:
Client ID
Application name
Client group
Subscription list
Queue of documents not yet acknowledged (“unacked” documents)

Client Groups
Client groups provide a method for setting important properties for a group of Broker
clients. Instead of assigning properties to each Broker client separately, you can assign
properties to a client group. Properties you assign to a client group include:
Client life cycle
Client queue storage type
Subscribe and publish access to document types

Log Publish and Log Acknowledge
Access control list
webMethods Broker Management

The webMethods Broker management tools consist of the Broker Administrator,
command line utilities, and the webMethods JMS Administrator. These tools allow
application developers and system administrators to configure and manage the document
traffic that flows through a Broker Server. They also provide access to information about
the Broker Server, Brokers, Broker clients, client groups, document types, Secure Sockets
Layer support, and error logging.
Broker Administrator
Broker Administrator uses the browser on the local machine and the Integration Server,
which can be anywhere in the network, to connect to a Broker Server. The Integration
Server is installed using the webMethods installation program.
The Broker Administrator allows you to configure administrative websites from which
you can monitor webMethods Broker Servers, territories, Adapters, Brokers, and clients
from any browser-equipped workstation in your organization’s network.
You set up the Broker Administrator on any Integration Server during the Broker Server
installation. For instructions on installing the Broker Administrator, refer to the
webMethods Installation Guide.
To learn how to start the Broker Administrator, see Chapter 2, “Logging On to Broker
Administrator.”

webMethods Broker Management
Command Line Utilities

The webMethods Broker installation includes several utilities that you run from the
command line (UNIX shell or Windows DOS prompt).
The following utilities are located in the webMethods Broker installation Broker/bin
directory:
Command Line Utilities Description

awcert Changes the password on a certificate file.
broker_create Creates a Broker on the Broker Server.
broker_buildall Compiles all intelligent integration components and
scripted operations from a Broker.
broker_delete Deletes a Broker on the Broker Server. When you run this
command, the named Broker leaves its territory, if it belongs
to one. All client queues on the Broker are lost, all client
queues are disconnected; and the Broker, all of its document
types, and client groups are deleted permanently.
broker_load Imports Broker data from a file to a Broker.
broker_ping Pings Broker to verify operational status.
broker_save Saves Broker configuration information for a specified
Broker to a file.
broker_start Starts the Broker Server.
broker_status Displays statistics for a Broker on the Broker Server. The
statistics displayed include Broker status, document
delivery statistics, and client statistics.
broker_stop Stops the Broker Server.
jmsadmin With the jmsadmin command line tool, you can perform a
variety of functions. Generate and manage administered
objects and bind them to a JNDI context. Browse JNDI
contexts. Create the Broker through which JMS clients
exchange messages. Manage permissions for topics and
queues. Create batch files of JMSAdmin commands to
automate the management of administered objects.
For more about the jmsadmin command line tool, see the
webMethods Broker JMS Provider Programmer’s Guide.

Command Line Utilities Description

server_conf_backup Creates a backup of the Broker Server’s configuration data
storage while the Broker Server is still running.
server_conf_restore Restores a Broker Server’s configuration data storage from a
previous backup created by server_conf_backup.
server_config Creates and configures Broker Servers.
The command line utilities are described in detail in Appendix A, “webMethods Broker
Command Line Utilities.” For more about the jmsadmin command line tool, see the
webMethods JMS Administrator

webMethods JMS Administrator uses the browser on the local machine and the
Integration Server, which can be anywhere in the network, to connect to a Broker Server.
The Integration Server is installed using the webMethods installation program.
The webMethods JMS Administrator allows you to configure administrative websites
from which you can configure and manage JMS administered objects.
You set up the webMethods JMS Administrator on any Integration Server during the
Broker Server installation. For instructions on installing the webMethods JMS
Administrator, refer to the webMethods Installation Guide.
To learn how to start the webMethods JMS Administrator, see Chapter 12, “Configuring
Administered Objects with the JMS Administrator.”

Setting Up a webMethods Broker Server
Setting Up a webMethods Broker Server
To set up a webMethods Broker Server
1 Install the webMethods Broker software.

Refer to the webMethods Installation Guide for complete installation instructions.
2 Verify that the default Broker is running by using either Broker Administrator or the
broker_status command. See “Displaying Broker Statistics” on page 36 for
instructions. M
The default Broker is created when the webMethods Broker software is installed. If
you do not see the default Broker, or if the Broker is not running, check to make sure
that the Broker Server is running. For installation troubleshooting tips, refer to
Appendix B, “Tips and Troubleshooting.”
3 If needed, install and configure adapters.
Adapters are necessary to translate information between the format required by a
resource and the format used by a webMethods Broker document.
Refer to the webMethods Installation Guide and the documentation for your adapter for
installation and configuration instructions.
4 Configure the default Broker.
When you configure the Broker, you specify properties for the following components:
Client Groups. Specify the client queues and subscriptions that you want monitored
and stored. See Chapter 6, “Managing Client Groups.” for detailed instructions.
Clients. List the client programs to which the Broker Server connects.
See Chapter 8, “Managing Broker Clients.”for detailed instructions.
Document types. Define the type of information you want exchanged by the Broker.
See Chapter 7, “Managing Document Types.” for detailed instructions.
To configure the Broker, you can also import Broker information from an existing
Broker. See Chapter 4, “Managing Brokers,” for more information.
5 Optionally, create and configure additional Brokers. See Chapter 4, “Managing
Brokers.” to learn how to create additional Brokers.
6 Verify that expected Broker clients are connected to the Broker. See Chapter 8,
“Managing Broker Clients.” to learn how to view the status of a Broker client
7 Optionally, add an existing Broker Server to the list of Broker Servers being
monitored by the Broker Administrator.
To configure and manage the Broker Servers on your network, you must first add
them to the Broker Administrator.

See Chapter 3, “Managing webMethods Broker Servers.” to learn how to add existing
Broker Servers to the Broker Administrator.
8 Optionally, configure and manage territories and territory gateways.
A client on one Broker can communicate with a client on another Broker within the
same territory. Territory gateways provide control over documents that pass from
one territory to another. Using gateways, it is possible for clients to communicate
across administrative domains.
See Chapter 10, “Territories and Gateways.” to learn how to set up territories and
gateways.
9 Optionally, set up Secure Sockets Layer (SSL) support.
SSL provides a secure means of communication over a network between two
programs. To provide SSL support in webMethods Broker, you must enable SSL for
the Broker Server and for each client application, adapter, and/or the Broker
Administrator.
See Chapter 11, “Managing Broker Security.” to learn more about SSL support.
10 Publish a document to test your settings.

CHAPTER 2
Using the webMethods Broker Management Tools
Starting the webMethods Broker Management Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Quick Tour of Broker Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Basic Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

C H A P T E R 2 U s i n g t h e w e b M e t h o d s B r o k e r M a n a g e m e n t To o l s
Starting the webMethods Broker Management Tools

The webMethods Broker management tools include the webMethods Broker
Administrator and command line utilities. These administration tools provide you with a
variety of features and options to make administration easy and accessible.
Broker Administrator. You can perform webMethods Broker Server, Broker, client and
adapter monitoring and diagnostics from any browser-enabled workstation. To set up
the Broker Administrator, see the webMethods Installation Guide. To log on to the
Broker Administrator, see “Logging On to Broker Administrator” below.
Command line utilities. You can perform various webMethods Broker and Broker
management tasks using the command line utilities on your UNIX or Windows
system. For more information about using the command line utilities, refer to
Appendix A, “webMethods Broker Command Line Utilities.”
webMethods JMS Administrator. You can configure and manage JMS administered
objects. For more information, see Chapter 12, “Configuring Administered Objects
with the JMS Administrator”.
Logging On to Broker Administrator

To load the Broker Administrator, the following information is required:
URL for the Broker Administrator
Valid user name and password for administrator privileges
Host and port of the webMethods Broker to which you are connecting
Note: To load the Broker Administrator, the browser must be able to display images,
support frames and cascading style sheets, and must be able to run javascript.
To log on to the Broker Administrator
1 From the Start menu choose ProgramswebMethodsServersIntegration Server to start

your Integration Server.
2 Open a browser window.
3 Point your browser to the host and port where the Integration Server is running.
Examples:
If the Integration Server is running on the default port on the same machine where
you are running the Broker Administrator, you would type:
http://hostname:5555/WmBrokerAdmin/

Starting the webMethods Broker Management Tools
If the Integration Server is running on port 4040 on a machine called ATLAS, you
would type:
http://ATLAS:4040/WmBrokerAdmin/
Log on to the Integration Server with a user name and password that has
administrator privileges.
If you just installed the webMethods Integration Server, you can use the following
default values:
User Name: Broker
Password: manage
Use the exact combination of upper- and lower-case characters shown above (user
names and passwords are case sensitive).
Important! webMethods recommends that you change the password immediately

after installing webMethods Integration Server. Otherwise, your server will be
vulnerable to anyone who knows the default passwords that are installed on its
servers.
When you change the password, be sure to select one that is difficult to guess. For
example, use a mixture of upper- and lower-case letters, numbers, and special
characters. Do not use a name, phone number, social security number, license plate,
or other generally available information. See the webMethods Integration Server
Administrator’s Guide for instructions on changing the password.
If the Integration Server is not running, your browser will issue an error similar to
the following:
Cannot open the Internet site http://hostname:5555/WmBrokerAdmin/.
A connection with the server could not be established.
The Broker Administrator may take a few moments to load.

Quick Tour of Broker Administrator

Broker Administrator is divided into three frames: the banner, the Navigation panel, and
the main page as shown below.
Broker Administrator page
Banner
Navigation
panel
Main
page
The Banner contains the following options:

Administration. Opens the Integration Server page, where you configure Broker
Administrator authentication (user names and passwords) settings. From the
Integration Server Administrator page you can specify users and groups and define
the level of administrative access allowed to them. Refer to the webMethods Integration
Server Administrator’s Guide’s detailed instructions about using the Integration Server.
Logout. Allows you to end your current session.
About. Displays copyright and version information for the product.

The Network panel or Navigation panel is a navigation tree that displays Broker-related
objects that you can administer. Using this tree you can easily understand the structure of
a hierarchy of pages or objects and navigate quickly to a particular item in the structure.
The tree functions as a typical navigation tree. You simply expand and collapse the
structure as needed to obtain the view you want to see. Although there are sometimes
several ways to navigate to a particular page, the procedures in this book use the
Navigation panel method whenever possible.

The main page displays a screen that corresponds to the object you select from the
Navigation panel. From this page, you view and edit the settings for the webMethods
Broker Servers, Brokers, Adapters, and Territories on the network.
Viewing Broker Administrator

The Broker Administrator Navigation panel offers three different views of your
webMethods network: the Broker Servers view, Territories view, and Adapters view, as
shown in the figure on page 30.
The Broker Servers view displays statistics and general information for each
webMethods Broker Server. Once you add a Broker Server to the Broker Servers page,
you can edit and view its Brokers, error logs, and utilization statistics. For instructions
for viewing and editing webMethods Brokers, see Chapter 3, “Managing
webMethods Broker Servers.”
The Territories view displays the Brokers associated with each Territory, the gateway for
each Territory, and the document traffic for the last set number of minutes (the
default value is 1 minute). For instructions for viewing and editing Territories and
Gateways, see Chapter 10, “Territories and Gateways.”
From the Adapters view you can view adapters on all Broker Servers and territories or
sort by Broker Server name and territory name. Click an Adapter or Broker to view
additional information. For more information about adapters see the documentation
for your adapter.

Viewing Broker Servers, Territories, and Adapters

Network Broker Server view
Broker Servers
within the network
Network Territories view
Territories and
Brokers within
the network
Adapters view
Choose which
Adapters to view
Adapters as
associated with
Brokers within
the network
To switch between these views, click the appropriate link in the Navigation panel.

Notes on Using Broker Administrator
Customizing the View of Broker Servers

Once you add a Broker Server to the Broker Administrator, you can then determine if you
want that Broker Server to be visible each time you log on. For example, if you are
managing 100 webMethods Brokers on your company’s network, at times you may want
to view only a specific subset of those without permanently removing the other Broker
Servers from the Broker Administrator.
You can choose which Broker Servers you want to view on the Broker Administrator by
using the Known Brokers page. This page is available from the Navigation panel, under
Settings.
From the Known Brokers page, you can add new webMethods Brokers to your view,
show or hide Broker Servers that are already part of your view, and permanently remove
Broker Servers from your view. For instructions, see “Managing the webMethods Broker
Server” on page 44.
Sorting Information in Broker Administrator

If using Internet Explorer, you can control the order in which many of the items are listed
in the Broker Administrator. Click the icon in the column headings to sort the items
listed to meet your preferences. If you want to reverse the order, click the icon again.
Updating Information on Broker Administrator

Many pages contain information that can change as the state of the system changes.
You can update the information displayed on the Broker Administrator by clicking
Refresh Broker Server List from the Broker Server view or Refresh Territory List from the
Territory view on the main page.
By default, the information on the Broker Administrator automatically updates every 90
seconds. You can turn this setting off or adjust the amount of time that should pass before
the information is refreshed. You can change the refresh rate settings from the Display and
Refresh page. To access the Display and Refresh page, click Display and Refresh under
Settings on the navigation menu, then click Change Display and Refresh Settings.

Display and Refresh page
Setting Up Broker Administrator Permissions

You can set up user and group permissions for the Broker Administrator on the
Administration page. Open the Administration page by clicking Administration on the
Banner. For detailed instructions for setting up permissions and for more information
about the Administration page, see the webMethods Integration Server Administrator’s Guide.
Viewing and Changing Connection Settings

The Broker Administrator allows you to view and change its basic connection settings.
The connection settings determine how long the Broker Administrator will wait for a new
connection to a remote Broker Server, if SSL is used for the connections, and the time
interval between statistical polls.
To view the Broker Administrator’s connection settings, under Settings on the navigation
menu, click Connections.
To change the connection settings, on the Connections page, click Change Connection
Settings. Use the Change Connections Settings page to update the following options:
How long to wait for a new connection. This is the number of seconds that the Broker
Administrator maintains an idle connection to a remote Broker Server. If the idle
connection exceeds the number of seconds allowed, a timeout message will occur. If
you specify 0, there is no timeout limit; the Broker Server maintains the connection
until your local Broker Server is shut down. The default value is 10 second(s).
Use SSL encryption when available. When this check box is selected, remote Broker
Servers that are SSL-enabled will be connected to the Broker Administrator through
an encrypted connection. This option is enabled by default.
Note: An SSL connection cannot be made if the remote machine connecting to the
Broker Administrator is not SSL-enabled.
For detailed information about SSL support, see Chapter 11, “Managing Broker
Security.”

Time interval between statistical polls. This is the number of minutes that should pass
between statistical updates. The default value is 1 minute.
Viewing and Changing Client Filters

You can choose which Broker clients you want to view on the Broker Administrator by
using the Client Filters page. This page is available from the navigation menu, under
Settings.
From this page, you can view, add, and delete client filters. The default filters and
descriptions are listed below:
Admin. Lists only the administrative client connections, for example, the Logging
Utility Administrative client.
Connected. Lists only the clients that are currently connected.
Integration Server. Lists only Integration Server clients.
Show All. Lists all clients.
Trigger. Lists only clients with a trigger client ID. For information about triggers, see
the webMethods Developer User’s Guide.
You can also create a custom filter by clicking Add User Defined Client Filter. For information
about creating client filters and applying them to Brokers, see “Client Filters” on page 115.
Viewing and Changing Identity Settings

Using the Broker Administrator's Secure Sockets Layer (SSL) identity feature, it is possible
to limit administrative access to any webMethods Broker from the Broker Administrator.
The Identity Settings page (SettingsIdentity) allows you to import an SSL Identity, or
certificate file, to be used throughout a single management session. When SSL is enabled,
a valid certificate must be provided; otherwise, administration tasks are limited during
the session because access will be blocked to Broker Servers and Brokers. To navigate to
the Identity Settings page, click Identity in the Navigation panel under Settings.
To configure Broker Administrator to use SSL for secure management sessions, see
“Configuring Broker Administrator for SSL Support” on page 173 for instructions. If you
want to set up the Broker Administrator to use an SSL connection when connecting with a
webMethods Broker, see “Viewing and Changing Connection Settings” on page 32.

Basic Operation
Displaying webMethods Broker Server Properties

On the main page, click the webMethods Broker to view its properties. The Broker Server
Information page appears, displaying general information, which is described in the table
on page 34.
From the navigation menu you can access Broker Server properties, including Server
information, utilization statistics, error logs, and adapter information.
Broker Server Information page
The Broker Server Information page contains the information shown below.
Information Description
Name The name or the IP address of the Broker Server.
Port Port number on which the webMethods Broker is running.
Description A description of the webMethods Broker. Click the Change Broker Server
Description link to update this field.

Basic Operation
Status Status of the webMethods Broker.
A warning symbol ( ) appears if the Broker Server is running low on

disk space, if its license has expired, or its connection limit has been
exceeded. Click the icon to view more information and to restore the
status.
SSL The entry will be either a yellow warning symbol or a green check mark.
A green check mark indicates that SSL is configured

and working.
A yellow warning symbol indicates that SSL needs

to be configured.
Click the icon to view more information and to change the SSL settings.
For instructions for setting up SSL, see Chapter 11, “Managing Broker
Security.”
Access The entry will be either a yellow warning symbol or a green check mark.
Control
A green check mark indicates that Access Control is
configured and working.
A yellow warning symbol indicates that the associated

Access Control List (ACL) is not accessible and
identity settings must be configured.
Connections The number of connections within the licensed limit.
Version The version number of the webMethods Broker.
Created The date and time the webMethods Broker software was installed on the
webMethods Broker Host.
Running Includes the date and time the Broker Server started running.
Since
License Displays the date when the license expires. Click the License Expires value
Expires to view more information, such as:
License key
Expires
Territories are Permitted
Number of Connections Allowed
Number of SSL Connections Allowed

Displaying Broker Statistics

You can view statistical information about the Brokers on the Broker Server using the
Broker Administrator or the broker_status command.
The Brokers page of the Broker Administrator, which includes statistical information, is
described in the following section. The broker_status command is described in
Appendix A, “webMethods Broker Command Line Utilities.”
The Brokers Page

On the Broker Administrator:
1 From the Navigation panel, click Broker Servers.
2 From the list of Broker Servers, click the Broker Server you want to see.
3 From the Broker Server Information page, select the Brokers tab at the top.
Brokers page

Basic Operation
The Brokers page contains the information shown below.
Broker Name The name of the Broker.
Territory The territory to which the Broker belongs.
Note: You can view the Brokers within a territory and get their statistics
from the Territories view. See Chapter 10, “Territories and Gateways”
for more information.
Connected The status of the connection. Connection status is displayed in the

following ways:
Yes is displayed with a green check mark to indicate the Broker

is connected.
In Progress indicates the connection is in the process of being
established.
Closed indicates the connection is closed.
Error indicates a problem occurred and a connection could not be
established.
Connections The actual number of connections.
Recent The document traffic on the Broker for the last X minutes. Where X is
Deliveries the time interval between statistical polls. The default value is 1 minute.
To change the default setting, see “Viewing and Changing Connection
Settings” on page 32.
Default Broker
A green check mark identifies the default Broker on the
webMethods Broker.
Description A description of the Broker. You can update this field at any time by
clicking the Broker, then clicking Change Broker Description.
Click the Broker for which you want to view information and statistics.

Broker Information page
The Broker Information page contains the statistics shown below.
Name The name of the Broker.
Description A description of the Broker. You can update this field at any time by
clicking the Broker, then clicking Change Broker Description.
Connected The status of the connection. Connection status is displayed in the
following ways:
Yes is displayed with a green check mark to indicate the Broker

is connected.
In Progress indicates the connection is in the process of being
established.
Closed indicates the connection is closed.
Error indicates a problem occurred and a connection could not be

established.
Default Broker Whether this Broker is the default Broker. A green check mark identifies
the default Broker on this webMethods Broker.
Created The date when the Broker was created.

Basic Operation
Document Whether document type logging is enabled. For more information
Type Logging about document type logging, see “Setting Up Your webMethods
Broker for Higher Performance” on page 68.
Document The number of document types associated with the Broker.
Types
Transactions The number of transactions that are currently executing on the Broker.
Because transactions are short-lived, typically only milliseconds, they
often complete too quickly to register in this field. A value of zero does
not necessarily mean there are no transactions executing.
Territory The territory to which the Broker belongs.
Note: You can view the Brokers within a territory and get their statistics
from the Territories view. See Chapter 10, “Territories and Gateways”
for more information.
Gateways Gateways to Brokers in other territories.

Clients The number of Broker clients connected to the Broker.
Client Groups The number of client groups assigned to the Broker.


PART II
Broker Server and Broker Administration
Managing webMethods Broker Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Managing Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Copying, Saving, and Restoring Configuration Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

CHAPTER 3
Managing webMethods Broker Servers
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Managing the webMethods Broker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Creating a webMethods Broker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Adding a Broker Server to Broker Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Adding Multiple Broker Servers to Broker Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Removing a Broker Server from the Broker Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Monitoring webMethods Broker Server Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Updating the webMethods Broker Software License Key . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Logging webMethods Broker Server Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Copying webMethods Broker Server and Broker Information . . . . . . . . . . . . . . . . . . . . . . . . 53

Configuring webMethods Broker Servers from the Command Line . . . . . . . . . . . . . . . . . . . 55
Using Separate Storage Sessions and Online Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Configuring the Storage Cache Size for a webMethods Broker Server . . . . . . . . . . . . . . . . 56

Configuring webMethods Broker to Use Asynchronous Write Mode . . . . . . . . . . . . . . . . . . . 57
Configuring webMethods Broker Monitor Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Stopping and Starting a webMethods Broker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Shutting Down the webMethods Broker System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

CHAPTER 3 Managing webMethods Broker Servers
Overview
The Broker Server manages the flow of documents among clients, Broker Servers and
various applications. To do this, the Broker Server automatically routes, queues, and
filters documents. The Broker Server guarantees information delivery over networks that
may have intermittent connectivity, such as dial-up connections. All webMethods Broker
components communicate with a Broker Server, not with each other.
The Broker Server has an associated data directory. The files in the data directory contain
information about the Broker Server’s configuration, and about the configuration and
statistics for each of the Brokers that manage the various queues through which
documents pass from one client to another.
It is possible to have more than one Broker Server running on a host. Each Broker Server
has its own data directory and communicates through its own port. Each Broker Server is
identified by the name of the host computer and the port number. For example, a Broker
Server running on port 6840 on the Broker Server Host named “atlas” is identified as
“atlas:6840”. Broker Servers on a host do not have to be the same version of webMethods
Broker.
This chapter describes how to carry out Broker Server administration tasks from the
Broker Administrator, how to configure Broker Servers from the command line, and how
to back up Broker Server data directories.
Managing the webMethods Broker Server

The following sections describe administration tasks you can perform on the Broker
Server.
Creating a webMethods Broker Server

The Broker Server installation software creates a default Broker Server that runs on port
number 6849. To create additional Broker Servers on the same Broker Server Host, use the
server_config command-line program. See “server_config create” on page 237 for
detailed instructions.

Adding a Broker Server to Broker Administrator

You can configure and manage the default Broker Server and other Broker Servers on
your network from Broker Administrator.
To begin, you must first add the Broker Servers you want to configure to the Broker
Server’s view. There are three ways you can add a Broker Server to the Broker Server’s
view.
Use the Add Known Broker Server option. You will need to specify the name and port
number of the Broker Server. Detailed instructions are given below.
Use the Discover Broker Server option. This option allows you to add multiple Broker
Servers running on the same host. To use this option, Broker Monitor must be
running on the host. You will need to specify the name of the host on which the
Broker Server runs. Detailed instructions are given below.
Use the Upload Broker Server List option. This option allows you to populate the Broker
Server view with multiple Broker Servers all at once. For instructions for using this
option, see “Adding Multiple Broker Servers to Broker Administrator” on page 46.
Add a Broker Server to the Broker Server’s view
1 Open the Broker Administrator if it is not already open.

2 Do one of the following:
On the Broker Servers view, click Change Broker Server List.
From the Navigation panel, on the Settings menu, click Known Broker Servers.
3 If the Broker Server you want to add is shown in the list of Known Broker Servers skip
to step 8. If the Broker Server is not shown, do the following:
a Click Discover Broker Servers.
b In the Hostname field, enter the name of the host on which the Broker Servers you
want to discover reside.
c Click Discover. You are returned to the Known Broker Servers page.
4 On the Known Broker Servers page, click Add Known Broker Server.
5 On the Add Broker Server page, in the Hostname field, type a valid name for the
Broker Server. The name can be the actual name of the host where the Broker Server is
running or the IP address. The Broker Administrator uses this value for the Broker
Server name.
6 If your Broker Server does not use the default port number 6849, type the correct port
number in the Port field.
7 Click Add.

The Broker Server is appended to the Broker Server list and displayed with the name
you entered.
8 Perform one of the following:
To add additional Broker Servers, follow Steps 2–5.
To show or hide Broker Servers in the Broker Server list, click Change Which Broker
Servers are Visible.
When a Broker Server is installed, the install program creates a Broker and makes it the
default. You can add new Brokers to a Broker Server at any time. See “Creating New
Brokers” on page 66.
Adding Multiple Broker Servers to Broker Administrator

If you are adding multiple Broker Servers to Broker Administrator, you can save time by
using the Upload Broker Server List option. Using this option, you can add all the Broker
Servers to Broker Administrator at once. This is especially useful when you must populate
more than one Broker Administrator with multiple Broker Servers.
The Upload Broker Server List option imports a Broker Server List file, which contains the
name and port number of each Broker Server. You create this file using the text editor of
your choice. See the next section for instructions for creating a Broker Server List file.
Creating a Broker Server List File

In the text editor of your choice, create a new file and list each Broker Server you want to
add to the Broker Administrator. Include the name and, optionally, the port number of
each Broker Server. Separate each entry with a return, comma, space, tab or semicolon.
broker_server_name1
broker_server_name2:port
broker_server_name4
Where broker_server_name and port represent the name and port of the Broker Server that
you want to add. For example:
california
tokyo:9000
paris:7000
newyork
london:8000
Save the Broker Server List file as an ASCII text file; it must have a .txt extension in order
for Broker Administrator to import it.

Importing a Broker Server List File
To import a Broker Server List file
1 Create a Broker Server List file. See the previous section for instructions.
On the Broker Servers view, click Change Broker Server List.
From the Navigation panel, on the Settings menu, click Known Broker Servers.
4 On the Known Broker Servers page, click Upload Broker Server List.
5 Enter the file name and location in the Filename field or click Browse to navigate to the
file.
6 Click Upload.
Removing a Broker Server from the Broker Administrator

When you remove a Broker Server from the Broker Administrator, the Broker Server does
not shut down; you are only removing it from the Broker Administrator application. For
instructions for shutting down a Broker Server, see “Shutting Down the webMethods
Broker System” on page 62.
To remove a Broker Server from the Broker Administrator

2 From the Navigation panel, on the Settings menu, click Known Broker Servers.
3 On the Known Broker Server Settings page, click Remove One or More Broker Servers.
4 In the Known Broker Servers list, select the check box next to the Broker Server you
want to remove.
5 Click Remove.

Monitoring webMethods Broker Server Usage

To gather more information about how your system is functioning, you can check the
usage statistics about a Broker Server. This information includes the amount of CPU time
the Broker Server is using, total amount of memory available, and how much storage
space is available.
You can view Broker Server usage information from the Broker Server Usage page. The
Broker Administrator displays utilization information using percent ratios and bar
graphs.
To display Broker Server usage information

2 From the Navigation panel, click the Broker Server for which you want to view usage
information.
3 On the Broker Server Information page, under the Broker Server menu, click the
Utilization tab.
The webMethods Broker Server Utilization page contains the following information.
Usage Statistics Explanation
CPU This statistic is available on UNIX systems only.

Used. Percentage of CPU time the Broker Server is currently
using.
Free. Percentage of CPU time that is available on the Broker
Server.
Virtual Memory Total. Amount of swap space available on the computer.
Used. Percentage of memory used.
Free. Percentage of memory unused.

Usage Statistics Explanation
Storage Session # Session URL. Location and type of storage facility

configuration.
Session Usage. Usage types:
– Config represents Broker Servers, Territories, Brokers, Doc
Types, and Statistics.
– Data represents client queues, documents, and logs
Total Storage. Represents the maximum space available,
space used, total storage space reserved, and maximum
transaction size for the Broker Server.
Storage. Lists the following information about each storage
file:
– Location of each storage file configured for the
Broker Server. Note that the default storage file has
a .stor extension
– Maximum size to which each storage file can grow
– Current space used in each storage file
– Current size of each storage file
Updating the webMethods Broker Software License Key

You can check to see when the webMethods Broker software (runtime) license key expires
on your system, and then update it if necessary.
To check or update the Broker Server license key

2 From the Navigation panel, click the Broker Server for which you want to view the
license key number.
3 To update the license key, click Change Broker Server License Settings.
4 In the Broker Server License field, enter a valid license key.
5 Click Save Changes.

Logging webMethods Broker Server Activity

The Broker Administrator lets you select the type of Broker Server activity you want to log
and lets you choose where the log information should be sent. By default, the Broker
Administrator uses whatever native logging facility is available on your system. For
example, on Solaris systems, Broker Administrator logs information in syslog.
Broker Administrator can also send messages that the Broker Server generates to other
computers via the Simple Network Management Protocol (SNMP). To see the messages
that the Broker Administrator sends, you must have an SNMP management system
configured with an SNMP viewer, such as Hewlett-Packard’s OpenView. To learn how to
set up and configure your SNMP viewer, see the documentation for your system’s
management software.
Configuring Log Options

When you configure log option settings, you configure them for the Broker Server and not
for the individual Brokers. The logging options for a Broker Server affect all the Brokers
that reside on the host.
To view the error log

2 Select the Broker Server for which you want to view error log options.
3 From the Broker Server Information page, click the Broker Server Log tab.
From this page you can view the current error log settings and entries. You can use
the options in the What to Display box to display the entire log or to only display
those messages occurring in the past set number of days.
4 Click Refresh Display to update the error log.
To edit the log option settings

2 Select the Broker Server for which you want to edit logging options.
3 From the Broker Server Information page, click Change Broker Server Log Settings.
A log settings page appears. From this page you can view the What to Log and How to
Log settings.
4 Click Edit Broker System Log Settings to change the What to Log and Where to Log
attributes.

5 Under What to Log, select one or more of the following options.
Select... To...
Alert conditions Include errors requiring timely administrative action.

Examples include full disks, missing data files, or a
misconfigured network.
Warnings Include potential errors that could lead to alert
conditions if ignored. Examples include low disk
space and license expirations.
Other information Include messages about starting and stopping the
Broker Server.
6 Under Where to Log, specify how you want to send the logged information. You can
select one or more of the following options.
Select... To...
Write to UNIX Syslog For Solaris or HP-UX, syslog messages are sent from the Broker
Server to the syslogd. Then, syslogd writes the messages to files,
consoles, or other machines, depending on how syslogd is
configured.
To view the messages, look at the log files shown below:
AIX: /var/opt/activesw/ broker.alert
/var/opt/activesw/broker.info
HP-UX: /var/adm/syslog/broker.alert
/var/adm/syslog/broker.info
Solaris: /var/log/broker.alert
/var/log/broker.info
Use the dropdown box to select a facility that is not currently

used by another application. The default is local5.
Write to Windows For Windows, messages are sent from the Broker Server to the
Event Log Event Log, which is typically located in the Administrative Tools
program group. To view messages, use the Event Viewer and
choose Log Application.
Generate SNMP traps This causes notifications to be sent to SNMP traps in your
systems management software (such as HP OpenView), for all
messages that get logged to the system event log.
Your systems management software should be configured with
the Broker Server MIB file (ACTIVESW.MIB can be found in
install directory/LIB directory).

By default, the Broker Server logs its errors using the native logging facility of the
platform on which it runs.
Messages are in one of two categories:
Broker Server. Messages in the Broker Server category are from the awbroker
process. The awbroker process is where all the standard Broker Server tasks take
place.
webMethods Broker Server Monitor. Messages in the webMethods Broker Server
Monitor category are from the awbrokermon process. The awbrokermon process
is always running once the Broker Server is installed, and is responsible for
starting and monitoring the awbroker process. For more information, see
“Configuring webMethods Broker Monitor Logging” on page 58.
Using the Broker System Log Display

The Broker System Log page does not have a limit on the number of messages it can
display. You can control the number of messages displayed by setting a time limit for the
messages. You can also preserve the messages in a file using the Export Log option. When
you are ready to clear all the entries in the error log, you can use the Purge option.
Exporting the Broker System Log

When you export a broker system log, a text file is created. The first line of the text file
provides information about the export operation: which messages are included, the
Broker Server name, and the date and time the export operation took place. Subsequent
lines contain the following information:
Type of log entry: Info, Warning, or Alert
Date and time of message
Broker-assigned message number
Message text
To export log messages

2 Select the Broker Server from which you want to export log messages.
3 From the Broker Server Information page, click the Broker Server Log tab.
4 Click Export Broker Server Log to File.

5 Use the dropdown list to select messages for export.

You can select all messages older than a specified day, all messages newer than a
specified day, or all messages in the log.
6 Click Export Log.
7 Broker Administrator exports the error log to a compressed file. Download the file by
clicking Click here to download Broker System Log Zip-File.
8 If your operating system asks whether you want to open the file or save it, click Save.
9 Navigate to the directory where you want to store the file, enter a filename, and click
Save.
Note: To unzip the error log file on Windows systems, you can use any archive utility
available for Windows. On UNIX systems, use the Gzip data compression program.
Purging the Broker System Log

You can delete the entries from the current Broker System Log.
To purge the message log

2 Select the Broker Server for which you want to purge log messages.
3 From the Broker Server Information page, click the Broker System Log tab.
4 Click Purge Broker System Log.
5 In the dropdown list, select the messages you want to purge.
You can select all messages older than a specified day or all messages in the log.
6 Click Purge Log.
Copying webMethods Broker Server and Broker Information

You can copy Broker Server information from one Broker Server to another. You can also
copy Broker information from one Broker to another on the same Broker Server or on a
different Broker Server.
Broker Server configuration information includes:
Broker Server description
Logging configuration

SSL configuration
Access Control List
Broker configuration information includes:
Broker description
Document type Definitions
Client group definitions
Territory information
Gateway information, including shared document types
Access Control Lists for client groups, territories, and territory gateways
This information also describes the configuration of a webMethods Broker system that can
contain multiple territories and the gateways that connect them.
Methods of Copying Broker Server and Broker Information

There are a number of features available for copying Broker information. These features
eliminate the time-consuming task of manually entering client group and document type
information into each Broker you want to deploy.
Clipboard feature of the Broker Administrator
This feature allows you to copy information from one Broker to another without
using ADL files. This method is easier and faster, but you can only use it to copy
information between Brokers that are viewable from the same Broker Administrator.
For more information, see “Using the Clipboard Feature of the Broker Administrator
to Copy” on page 77.
Broker command line tools
You can use the broker_save command to export Broker information from one
Broker into an ActiveWorks Definition Language (ADL) file. You can then use the
broker_load command to import the information/ADL file into another Broker. For
more information about using the broker_save and broker_load command line
tools, see “Using Broker Command Line Tools to Copy” on page 77.
Import/Export feature of the Broker Administrator
This feature allows you to perform export and import functions using ADL files, but
more conveniently than with the command line tools. In addition, and you have the
option of copying subsets of information. For information, see “Using the ADL
Export/Import Feature of the Broker Administrator to Copy” on page 78.
For more information about selecting a method, see “Copying Broker and Broker Server
Information” on page 75.

Configuring webMethods Broker Servers from the Command Line
Configuring webMethods Broker Servers from the Command

Line
You can use the server_config command line tool program to create and configure
Broker Servers. You must run this tool on the same host where the Broker Server resides
(with the exception of the list subcommand, which lists known Broker Servers on any
host). See Appendix A, “webMethods Broker Command Line Utilities,” for more
information.
Using Separate Storage Sessions and Online Backup

webMethods Broker 6.5 supports separate storage sessions for Broker configuration and
run-time data.
Broker configuration data includes Brokers, client groups, territories, gateways,
clients, access control lists, and document types.
Run-time data refers to client queues and actual documents.
With the separate storage configuration, you can use the online backup feature to backup
the configuration data storage while Broker continues to process document publishing
and delivery requests.
Diagram of webMethods Broker 6.5 separate storage sessions and online backup
Broker
Online
Backup Runtime
Meta-data
data
Offline
storage
In the unlikely event when the Broker configuration data becomes corrupted, the backup
copy of the configuration data storage will enable you to restore the Broker quickly,
without having to rebuilt it using ADL files. The backup option is not available for the

run-time data. For more information about the online backup feature, see “Backing Up
and Restoring System Configuration Data Storage” on page 85.
If you have no need to back up your Broker configuration data storage, you can continue
to use the combined storage configuration where both the Broker configuration and run-
time data are stored in a single storage session. You can backup a combined data file for
the purpose of a system configuration restore, if you completely drain all Broker queues
and shut down the Broker Server. For more information, see “Backing up and Restoring
Combined Broker Server Storage” on page 88.
Note: At this time, there is no direct path to convert from a combined storage to a separate
storage configuration or vice-versa. If you would like to take advantage of the Broker
Server online configuration data storage backup and restore feature, you must create a
new Broker Server with separate configuration and run-time data storage sessions and
populate the new Broker Server with ADL files exported from the existing Broker Server.
For more information, see the webMethods Broker Upgrade Guides.
Configuring the Storage Cache Size for a webMethods Broker

Server
The Broker Server provides a setting, max-cache-size, in the Broker Server's configuration
file for controlling the storage cache sizes for the storage system.
For separate storage sessions, there are two separate storage caches: one for each storage
session. For combined storage session, there is a single storage cache.
For configuration data storage session:
Minimum max-cache-size = 8MB
Default max-cache-size = 8MB
For run-time data storage session:
For combined storage session:
You specify the max-cache-size value by pending it to the storage session URL string, using
the following extended format:
qs://<fully path to the .qs file>[?<argument>]

Configuring webMethods Broker to Use Asynchronous Write Mode
For example, if you want to change cache size for the configuration data storage session to
64MB, you modify the configuration data storage session URL as follows:
session-config=qs:///var/opt/BrokerStorage/BrokerConfig.qs?max_cache_size=64
If you want to change cache size for the run-time data storage session to 512MB, you
modify the run-time data storage session URL as follows:
session-data=qs:///var/opt/BrokerStorage/BrokerData.qs?max_cache_size=512
If you want to change cache size for the combined storage session to 512MB, you modify
the combined storage session URL as follows:
session-config=qs:///var/opt/BrokerStorage/BrokerConfig.qs?max_cache_size=512
Note: The use of max-cache-size=nnn as a separate entry in the awbroker.cfg file has
been deprecated for webMethods Broker Version 6.5. For a combined storage session,
the values specified in the storage session URL overwrite the max-cache-size=nnn
value. This value should not be used for separate storage sessions.
To change the storage cache size in awbroker.cfg

1 Stop the Broker Server. For instructions, see “Stopping and Starting a webMethods
Broker Server” on page 61.
2 Use an editor to open the awbroker.cfg file located in the Broker Server’s data
directory and make the appropriate modifications.
Note: If you want to modify the max-cache-size for your storage session and enable
asynchronous write mode, you append both parameters to the storage session URL, for
example:
session-data=qs:///var/opt/BrokerStorage/BrokerData.qs?max-cache-size=512?async
3 Save the file.

4 Restart the Broker Server for the new setting to take effect. For instructions, see
“Stopping and Starting a webMethods Broker Server” on page 61.
Configuring webMethods Broker to Use Asynchronous Write

Mode
The Broker Server provides a storage configuration flag, async, in the Broker Server’s
configuration file for enabling Broker Server to use the asynchronous disk write mode
when writing data to disk. When asynchronous write mode is enabled, the Broker Server
will allow the operation system to cache its disk write requests. This will significantly
increase the guaranteed document performance. See “Setting Up Your webMethods

Broker for Higher Performance” on page 68 for more details on how to improve your
Broker performance.
Note: There is a potential for losing guaranteed documents if the operating system cache
is not flushed to the disk before a failure occurs with the operating system or the host
computer. Asynchronous write mode is not recommended if you require a high degree
of reliability for guaranteed document delivery.
You enable the asynchronous write mode by pending the async flag to the storage session
URL string, using the following extended format:
qs://<fully path to the .qs file>[?<argument>]
For example, if you want to enable asynchronous write mode for the run-time data
storage session, you modify the run-time data storage session URL as:
session-data=qs:///var/opt/BrokerStorage/BrokerData.qs?async
If you want to enable asynchronous write mode for the combined storage session, you
modify the combined data storage session URL as:
session-config=qs:///var/opt/BrokerStorage/BrokerConfig.qs?async
Note: If you want to enable asynchronous write mode and modify the max-cache-size for
your storage session, you append both parameters to the storage session URL, for
example:
session-data=qs:///var/opt/BrokerStorage/BrokerData.qs?max-cache-size=512?async
Configuring webMethods Broker Monitor Logging

Currently, the Broker Monitor logs all informational, warning and error logging and by
default, the Broker Monitor logging is enabled. However, by manually editing the Broker
Monitor’s configuration file (awbrokermon.cfg), you can configure the Broker Monitor to
disable and enable the logging feature.
The format of the awbrokermon.cfg file is “key=value”, where each key starts with either
“server-” or “monitor-” to denote values that refer to a Broker Server or to the Broker
Monitor itself.
Key Description Value Type

monitor-log-alert Logging of alerts enabled Integer*
monitor-log-warning Logging of warnings enabled Integer*
monitor-log-info Logging of informational messages enabled Integer*
monitor-log-syslog- Destination for UNIX Syslog messages String
facility

Configuring webMethods Broker Monitor Logging

monitor-log-syslog Logging to UNIX Syslog enabled Integer*
monitor-log-eventlog Logging to Windows EventLog enabled Integer*
monitor-log-internal Logging to internal destination enabled Integer*
monitor-log-snmp Logging to SNMP enabled Integer*
* where: 0 = disabled
1 = enabled
-1 = permanently disabled
By default, the Broker Monitor values are as follows:

UNIX: 1,1,1,”local5”,1,-1,1,1
The -1 value means “permanently disabled,” so there is no Eventlog on the UNIX
platforms (including Solaris, AIX, or UNIX).
Windows: 1,1,1,“local5”,-1,1,1,1
The -1 value means “permanently disabled,” so there is no Syslog on Windows 2003
and XP.
You can manually edit the awbrokermon.cfg to disable and enable the Broker Monitor
logging feature.
To disable Broker Monitor logging

1 Stop the Broker Monitor. For more information, see “broker_stop and broker_start”
on page 262 or “Shutting Down and Restarting a Broker Server on Solaris, HP-UX,
and Windows Platform” on page 63.
2 Use your text-based editor to edit the following key values in the awbrokermon.cfg
file to disable a specific Broker Monitor logging setting. Each setting is controlled by
adding a line in the format “key=value” followed by a new line. The “key” is one of
the keys listed in the table below (e.g., monitor-log-alert) and the value is either a
number or a string, depending on the key.
monitor-log-alert Logging of alerts enabled Integer*

monitor-log-warning Logging of warnings enabled Integer*
monitor-log-info Logging of informational messages enabled Integer*
monitor-log-syslog- Destination for UNIX Syslog messages String
facility
monitor-log-syslog Logging to UNIX Syslog enabled Integer*

monitor-log-eventlog Logging to Windows EventLog enabled Integer*

monitor-log-internal Logging to internal destination enabled Integer*
monitor-log-snmp Logging to SNMP enabled Integer*
* where: 0 = disabled
1 = enabled
-1 = permanently disabled
For example, to disable monitor-log-alert, you would type:

monitor-log-alert=0
And to disable both monitor-log-alert and monitor-log-info, you would type:

monitor-log-alert=0
monitor-log-info=0
3 Restart the Broker Monitor. For more information, see “broker_stop and broker_start”
To re-enable Broker Monitor logging

1 Stop the Broker Monitor. For more information, see “broker_stop and broker_start”
2 To re-enable Broker Monitor logging, use your text-based editor to edit the
awbrokermon.cfg file. Find the statement that you previously added to disable Broker
Monitor logging and either:
Delete the statement that disables Broker Monitor logging,
e.g., delete “monitor-log-alert=0”
OR
Change the value of the disabled key figure to 1,
e.g., change “monitor-log-alert=0”
to “monitor-log-alert=1”
3 Restart the Broker Monitor. For more information, see “broker_stop and broker_start”

Stopping and Starting a webMethods Broker Server
Stopping and Starting a webMethods Broker Server

Occasionally you may need to stop and restart a Broker Server. Examples are when you
want to back up files in the data directory to apply a service pack or perform other
maintenance work.
There are several ways to stop and restart a Broker Server:
From Broker Administrator, using the options available on the Broker Server menu
From the command line, using the broker_stop and broker_start programs
On Windows, from the Control Panel
Using the server_config program

Each method is described in the following sections.
Important! When you stop the Broker Server, all Broker clients are disconnected. No
Broker clients can reconnect and retrieve documents until you restart the Broker Server.
To stop and restart a webMethods Broker Server from Broker Administrator
1 Open Broker Administrator if it is not already open.

2 From the Navigation panel, click the Broker Server you want to stop and restart.
3 On the Broker Server page, click Stop/Restart tab.
4 On the Stop/Restart page, select one of the following:
Leave it Stopped to stop the Broker Server and restart it at a later time.
Restart it Immediately to automatically restart the Broker Server after stopping.
5 Click Stop/Restart Broker Server.
This action immediately stops all Brokers on the Broker Server from transmitting
documents. The Broker Server page changes to indicate that the Broker Server is not
running.
To stop and restart a webMethods Broker Server from the command line
You can use the broker_stop and broker_start command line tools to stop and
start the Broker Server. Refer to Appendix A, “webMethods Broker Command Line
Utilities,” for instructions.

To stop and restart a Broker Server on Windows systems
1 Open Administrative Tools, then double-click the Services icon.

2 In the Services dialog box, select webMethods Broker Monitor and click Stop.
This action immediately stops all Brokers on the Broker Server from transmitting
documents.
3 To restart the Broker Server begin transmitting documents again, click Start.
Shutting Down the webMethods Broker System

There may be times when you want to shut down the entire webMethods Broker system
on a Broker Server Host (not just the Brokers). For example, you need to shut down the
webMethods Broker system when you upgrade your system with a Broker Server system
patch, or when you want to upgrade your operating system.
webMethods Broker Server Processes

The webMethods Broker Server software consists of two processes, awbroker and
awbrokermon, whose relationship to each other is shown in the figure below.
webMethods Broker Server Processes
awbrokermon†
awbroker‡ awbroker
...
Broker Broker Broker ... Broker
Document Document Document Document
Subscriber Publisher Subscriber Publisher
† The awbrokermon is the system process, or daemon, that implements the

webMethods Broker Monitor.
‡ awbroker is the webMethods Broker Server process.

Shutting Down the webMethods Broker System
The awbroker process is where all Broker tasks take place. Some of these tasks include
receiving, queuing, and delivering documents. The awbroker process can support
more than one Broker, so you can create and deploy multiple Brokers for
development and administrative convenience.
Because multiple Brokers are supported by a single awbroker process, all actions that
affect the awbroker process also affect all Brokers that reside on the same Broker
Server. For example, shutting down the Broker Server shuts down all of its Brokers.
The awbrokermon process, which controls and monitors the awbroker process, is
always running once it is installed. The awbrokermon process starts and monitors the
awbroker process. For every Broker Server running on a host, there is a separate
instance of the awbroker process. A single awbrokermon process controls all
awbroker processes running on a host.
If the awbroker process stops unexpectedly, awbrokermon logs the fault and attempts
to restart awbroker. The awbrokermon process does not perform a restart if awbroker
has three unexpected exits within five minutes.
You can stop and restart the awbrokermon and awbroker processes by using specific
command line tools. See “broker_stop and broker_start” on page 262.
Shutting Down and Restarting a Broker Server on Solaris, HP-UX, and Windows
Platform
To shut down a Broker Server (awbrokermon and awbroker processes) on Solaris, HP-UX,
and Windows platforms, use the commands described in the following sections.
To shut down the webMethods Broker processes on Solaris
Note: On Solaris, you can only run these commands as user root or user bin. These
commands can only shut down webMethods Broker processes on the local machine.
1 To stop the awbrokermon process, enter this command:

/etc/rc3.d/S45broker65 stop
This command stops the webMethods Broker processes, awbrokermon and awbroker.
2 To restart the webMethods Broker processes, enter this command:
/etc/rc3.d/S45broker65 start

To shut down the webMethods Broker processes on HP-UX
Note: On HP-UX, you can only run these commands as user root or user bin. These
1 To stop the awbrokermon process, enter this command:

/sbin/rc3.d/S45broke65 stop
2 To restart the webMethods Broker processes, enter this command:
/sbin/rc3.d/S45broker65 start
To stop the webMethods Broker processes temporarily on Windows
Note: On Windows, any user with administrator privileges can start or stop any service.
You can start and stop services on a remote machine and a local machine if you have a
Domain established and have domain administrator privileges.
1 Open Administrative Tools, then double-click the Services icon.

2 In the Services panel, select webMethods Broker Monitor and click Stop. This action
also stops the webMethods Broker.
You can also change the webMethods Broker Server Monitor’s startup type so that it
cannot be started. In the Services dialog box, with the webMethods Broker Server
Monitor selected, click Startup. In the dialog box, change the Startup Type to Disabled
and click OK. You cannot restart the webMethods Broker Server Monitor until you
change the Startup type to Automatic or Manual.

CHAPTER 4
Managing Brokers
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Managing Individual Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Creating New Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Assigning Default Status to a Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Enabling Document Type Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Setting Up Your webMethods Broker for Higher Performance . . . . . . . . . . . . . . . . . . . . . . . 68
Deleting Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Name Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Uninstalling Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Deploying Additional Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Methods of Copying Broker Server and Broker Information . . . . . . . . . . . . . . . . . . . . . . . . . 72

CHAPTER 4 Managing Brokers
Overview
Each Broker Server has one or more entities, called Brokers, that reside on it. A Broker is
where the client programs connect to, where document types are stored, and where client
queues and subscriptions are monitored and stored. When you install a Broker Server, the
installation program creates one Broker and makes it the default Broker. This chapter
describes how to carry out Broker administration tasks such as creating and deleting
Brokers, and deploying copies of existing Brokers.
Managing Individual Brokers

The following sections describe basic administration tasks you can perform on individual
Brokers.
Creating New Brokers

You can create new Brokers on a Broker Server using Broker Administrator or the
broker_create command from the command line.
To create a Broker using Broker Administrator

2 From the Navigation panel, (or from the Broker Servers page) select the Broker Server
for which you want to create a new Broker.
3 On the Broker Server Information page, click the Brokers tab.
The Brokers page appears, displaying the Brokers that reside on the Broker Server.
See “Displaying Broker Statistics” on page 36 to learn more about the Broker
properties displayed on the Brokers page.
4 Click Create Broker on Broker Server Name, where Broker Server Name represents the
Broker Server on which you will create the new Broker.
5 On the Create page, enter a name for the new Broker in the Name field, then enter a
short description of the Broker in the Description field.
6 Optionally, select the Default Broker check box to make this the default.
7 Click Add.
The new Broker appears under the Brokers on Broker Server Name list, where Broker Server
Name represents the name of the Broker Server. Click the Broker to view and change its
information.

To create a Broker from the command line
If you want to work from the command line, rather than from Broker Administrator,
you can use the broker_create command to create a Broker. Refer to
“broker_create” on page 254 for instructions.
Assigning Default Status to a Broker

Any Broker on a Broker Server can be the default Broker. Initially, a default Broker is
automatically created when you install the Broker Server. You will not need to change the
default status of a Broker unless there are two or more Brokers on a Broker Server. One
reason for assigning default status to a Broker is so you can connect to a specific Broker
without having to remember its name. Note that you do not have to assign any Brokers on
a Broker Server to be the default.
You can identify the default Broker for a Broker Server on Broker Administrator by
looking at the Default Broker column on the Broker Information page. A green check mark
( ) indicates the default Broker.
To change the status of a Broker

for which you want to create a new Broker.
3 On the Broker Server Information page, click the Brokers tab.
4 On the Brokers page, click Change Default Broker.
5 On the Default Broker page, do one of the following:
Select the new default Broker.
Select None if you do not want to assign a default Broker to the Broker Server.
Enabling Document Type Logging

Enabling document type logging allows for logging of Broker documents and other
information into the Integration Server audit log tables.
Important! Before you enable this option, you must install the webMethods Logging
Utility and configure the Integration Server to receive Broker information. See
webMethods Integration Platform Logging and Monitoring Guide for more information
about setting up Broker document logging with the Integration Server.

After you enable document type logging, the Document Type Log Length field appears on the
Broker Administrator. This field displays the number of documents in the log queue.
Setting Up Your webMethods Broker for Higher Performance

A Broker uses files to store non-volatile documents. Additionally, it uses a swap file in the
case of volatile and guaranteed documents. The table on page 68 shows how the Broker
and Broker documents use physical memory, swap file, and disk space (system
resources).
All Brokers in a Broker Server share the same data storage and its limitations. Since the
data storage is not partitioned, one Broker could use all the storage. However, multiple
Broker Servers on the same machine do not share data storage, so each Broker Server is
independent.
When the Broker Server is active, the components that can use the resources are listed
below.
Code (webMethods Broker binary)
Volatile documents (if used)
Guaranteed documents (if used)
The table below assumes Solaris as the operating platform, so the following limitations
apply. (Windows can also be used, except you use page file size instead of swap size.
Windows requires additional page size since Windows pages less efficiently than Solaris.)
Limit of storage for volatile clients and documents on Solaris is determined by the
available virtual memory
Limit of guaranteed data size of approximately 1900GB
Queue storage data files size are configured using server_config program,
which is described on page 230.
The following table shows the resource usage for a Broker Server
Volatile
Code Documents Guaranteed Documents
System Swap no yes no
Physical Memorya yes yes yes
Disk Spaceb approx. 5 - 10 MB noc 1900GB max for queue

storage
a.At least 512MB of physical memory.

b.At least 750MB of disk space.
c.Volatile documents reside in memory. The limitation on the size is the available virtual
memory (physical memory plus swap size).

Improving Your Broker Performance

Faster document transaction, minimal resource requirements, and the type of document
data used in the system are all requirements to help improve performance on your Broker.
The following list provides some guidelines for improving performance.
Volatile documents. Key factors are CPU and physical memory.
You need enough physical memory to hold all volatile documents when Broker
queues are backlogged; otherwise, documents will have to swap to disk, which also
slows down performance.
Guaranteed documents. Key factors are disk and physical memory.
Disk speed is the main factor for performance of guaranteed documents. You can
improve guaranteed performance by using a disk with at least 32MB of non-volatile
write-back cache RAM. Most raid controllers include non-volatile write-back cache
RAM.
Asynchronous write mode. You can gain even more guaranteed performance by using
the operating system’s write cache. However, there is a potential for loss of data if the
operation system crashes. You can enable the Broker to use operating system caching
by setting asynchronous write mode using the server_config command. For more
information, see “Configuring webMethods Broker to Use Asynchronous Write
Mode” on page 57.
Sharing the host computer with other applications. Even though the Broker can run with
other applications on the same host computer, you need to be aware that potential
resource contentions between applications and the Broker(s) can lead to Broker
performance degradation. webMethods recommends that you run the Broker on the
dedicated host computer to ensure optimal performance.
webMethods Broker Document Sizes
Maximum Document Size

The maximum document size applies to all documents published in a single operation.
For example, if you publish ten documents in one operation, the total size is less than the
maximum document size.
You configure the maximum document size using the server_config program. The size
should be slightly less than that of the queue storage log file, but must fit in memory. See
“Understanding Client Group Properties” on page 94 to learn more about document
types and storage.
Guaranteed Documents
The maximum document size of a guaranteed document type is restricted to the size of
the log file (which is configurable) and the amount of virtual memory (which is divided
by 3 due to internal buffering).

Volatile Documents
You can publish volatile documents of an unlimited size up to the smaller of available
swap or the Broker’s volatile storage limit (restricted only by the available memory).
Broker's Guaranteed Storage

The Broker's guaranteed storage is a proprietary storage, known as Queue Storage (QS). It
is a highly reliable storage mechanism. It is used to store all of the Broker Server’s non-
volatile information, such as Brokers, document types, client groups, territory
information, and non-volatile client subscriptions and statistics. However, volatile clients
and volatile documents are not stored in guaranteed storage.
Storing data in guaranteed storage requires a transaction. The transaction is performed as
a logged commit that ensures that the data is either saved completely or not saved at all.
The logged commit is a process that guarantees document storage upon writing to the
configured log file and then sending to a storage file.
Deleting Brokers
You can permanently delete a Broker and all its Broker client, client group, and document
type information using Broker Administrator or the broker_delete command on the
command line.
To delete a Broker using Broker Administrator

from which you want to delete a Broker.
3 Click the Brokers tab.
The Brokers page appears, displaying the Brokers that reside on the Broker Server.
See “Displaying Broker Statistics” on page 36 to learn more about the Broker
properties displayed on the Brokers page.
4 Click Delete Brokers on Broker Server Name, where Broker Server Name represents the
Broker Server from which you will delete the Broker.
5 Select the check box next to the Broker you want to delete.
6 Click Delete.

To delete a Broker from the command line
If you want to work from the command line, rather than from Broker Administrator,
you can use the broker_delete command to delete a Broker. Refer to
“broker_delete” on page 256 for instructions.
Name Limitations
There are character limitations for Broker component names. The table below lists the
Broker component by name, the maximum length in bytes, and other rules and limitations
for naming.
Name Length in Bytes Notes

Broker 255 No @, /, or : . First character cannot be #
Document folder 255 Alphabetic followed by alpha numeric or _
Document type 255 Alphabetic followed by alpha numeric or _
Broker client 255 No @, /, or :. First character cannot be #
Client groups 255 No @, /, or :. First character cannot be #
Distinguished name no limit Any character (see “Distinguished Names”
on page 166).
Territory name 255 No @, /, or :. First character cannot be #
Unicode 6
Uninstalling Applications
At times you may need to uninstall a webMethods Broker application that did not
uninstall properly. When this happens you need to delete the Broker client and client
groups associated with the application.
For information about how to delete Broker clients or Broker client subscriptions, refer to
“Controlling Clients” on page 124.
For information about deleting client groups, refer to “Assigning “Can Publish” and “Can
Subscribe” Permissions” on page 100.

Deploying Additional Brokers

One of the main features of Broker Administrator is that it allows you to configure and
deploy multiple Brokers. For example, you may want to create multiple Brokers to share a
single Broker Server on a host during development so the work of multiple users does not
collide. Or you may want to deploy several identical Brokers to perform the same task at
different sites.
Methods of Copying Broker Server and Broker Information

There are a number of features available for copying Broker information. These features
eliminate the time-consuming task of manually entering client group and document type
information into each Broker you want to deploy.
Clipboard feature of the Broker Administrator
This feature allows you to copy information from one Broker to another without
using ADL files. This method is easier and faster, but you can only use it to copy
information between Brokers that are viewable from the same Broker Administrator.
For more information, see “Using the Clipboard Feature of the Broker Administrator
to Copy” on page 77.
Broker command line tools
You can use the broker_save command to export Broker information from one
Broker into an ActiveWorks Definition Language (ADL) file. You can then use the
broker_load command to import the information/ADL file into another Broker. For
more information about using the broker_save and broker_load command line
tools, see “Using Broker Command Line Tools to Copy” on page 77.
Import/Export feature of the Broker Administrator
This feature allows you to perform export and import functions using ADL files, but
more conveniently than with the command line tools. In addition, and you have the
option of copying subsets of information. For information, see “Using the ADL
Export/Import Feature of the Broker Administrator to Copy” on page 78.
For more information about selecting a method, see “Copying Broker and Broker Server
Information” on page 75.

CHAPTER 5
Copying, Saving, and Restoring Configuration Data
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Copying Broker and Broker Server Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Using the Clipboard Feature of the Broker Administrator to Copy . . . . . . . . . . . . . . . . . . . . 77
Using Broker Command Line Tools to Copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Using the ADL Export/Import Feature of the Broker Administrator to Copy . . . . . . . . . . . . . 78
File Formats for Saving ADL Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Saving and Restoring System Configuration Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Backing Up and Restoring System Configuration Using ADL . . . . . . . . . . . . . . . . . . . . . . . . 82
Backing Up and Restoring System Configuration Data Storage . . . . . . . . . . . . . . . . . . . . . . 85
Backing up and Restoring Combined Broker Server Storage . . . . . . . . . . . . . . . . . . . . . . . . 88

Backing up Broker SSL Certificate Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

CHAPTER 5 Copying, Saving, and Restoring Configuration Data
Overview
webMethods Broker Server and Brokers maintain a set of system configuration data.
Broker Server configuration information includes:
Logging configuration
SSL configuration
Access Control List
Broker configuration information includes:
Broker description
Document type definitions
Client group definitions
Territory information
Gateway information, including shared document types
Access Control Lists for client groups, territories, and territory gateways
This information also describes the configuration of a webMethods Broker system that can
contain multiple territories and the gateways that connect them.
When creating new Broker Server or Brokers, it may be more convenient to copy the
configuration data from an existing Broker Server or Broker instead of manually entering
the configuration data. This is especially true when migrating Broker Server and Broker
configuration data between different environments (e.g., from Test to Production).
There are two ways to copy the system configuration data between Broker systems:
The Clipboard feature of the Broker Administrator
Export/Import via the ADL (ActiveWorks Definition Language) file

The configuration data is stored in the Broker Server's storage system. When the Broker
Server starts up, it reads the configuration data from its storage into the memory. If the
Broker Server encounters difficulties in reading the configuration data, the Broker Server
startup process will fail. Therefore, it is important to back up the Broker Server and Broker
configuration data on a regular basis.
There a two methods for backing up the system configuration data:
For disaster recovery, e.g., from a configuration data storage failure, use the online
configuration data backup tool. You should back up your Broker Server's
configuration data storage immediately after you have made any configuration
changes.

Copying Broker and Broker Server Information
For point-in-time recovery, e.g., from user configuration error, use the ADL file export
capability. You should export your system configuration before you make any
configuration changes. However, the ADL file does not capture Broker territory and
gateway configuration information, therefore it is not possible to recover from
configuration errors in territory and gateway configurations using the ADL file.
This chapter describes how to copy Broker system configuration data for the purpose of
migrating system configuration between different environments and how to save Broker
system configuration data for the purposes of disaster recovery and point-in-time
recovery.

There are a number of features available for copying Broker and Broker Server
information. These features eliminate the time-consuming task of manually entering client
group and document type information into each Broker you want to deploy.
The method you choose depends on your needs.
Feature Description
Clipboard feature of The clipboard feature allows you to copy information from one
the Broker Broker to another without using ADL files. This method is easier
Administrator and faster, but you can only use it to copy information between
Brokers that are viewable from the same Broker Administrator.
Use this feature to:
Export all components or only a subset of components (for
example, only document types, or only client groups)
between machines that you know are viewable from the same
Deploy multiple Brokers.
For more information, see: “Using the Clipboard Feature of the
Broker Administrator to Copy” on page 77.

Feature Description
Broker command Use the broker_save command line tool to export Broker
line tools: information from one Broker into an ActiveWorks Definition
broker_save and Language (ADL) file. You can then use the broker_load
broker_load command line tool to import the information/ADL file into
another Broker.
Script the import /export process, especially when moving
through different environments.
Take regular scripted backups of metadata in your production
system
Process very large .adl files; the commands require less
memory than the import/export feature in the Broker Admin
UI.
For more information, see: “Using Broker Command Line Tools to
Copy” on page 77.
Export/Import Use this feature to perform export and import functions using
feature of the ADL files, but more conveniently than with the command line
Broker tools. In addition, you have the option of copying subsets of
Administrator information.
Export only a subset of components (for example, only doc
types or only client groups) to an ADL file.
Save an ADL file to disk, but do not want to use the
commands. For example, you could store this file in a source
code control system and move the file to a different machine
at a later date, when you move from a development
environment to a QA environment.
Copy information between machines that are not be on the
same network/not visible from the same Broker
Administrator, i.e., Brokers that reside on different Broker
Administrators.
For more information, see: “Using the ADL Export/Import Feature of
the Broker Administrator to Copy” on page 78.

Using the Clipboard Feature of the Broker Administrator to

Copy
This section describes how to copy Broker information using the Clipboard feature, which
is available through the Broker Administrator. The Clipboard feature copies information
between Brokers that can be viewed from the same Broker Administrator. The Brokers
can reside on the same or on different Broker Servers.
If you need to copy information between Brokers that reside on different Broker
Administrators, use the Import/Export feature. See “Using the ADL Export/Import
Feature of the Broker Administrator to Copy” on page 78 for more information.
Copying Broker Information Using the Clipboard Feature

2 From the Navigation panel, under the appropriate Broker Server, select the
component from which you want to copy information.
If you want to copy... Select...
All the information for a Broker That Broker

Just a client group That client group
Just a client That that client
Just a document type That document type
3 From the Information page for that Broker, Client Group, Client, or Document Type,
click Copy component Information to Clipboard, where component is Broker, Client Group,
Client, or Document Type.
Navigate to the Broker to which you want to copy the information. Select the Information
page of the Broker, Client Group, Client, or Document Type to which you want to copy
the information and click Paste component 'component_name' to current Broker.
Using Broker Command Line Tools to Copy

If you prefer to work from the command line, use the broker_save command line tool to
save a configuration file for each Broker Server and each Broker in the configuration.
To export the Broker Server data directory using broker_save

1 Stop the Broker Server. See “Stopping and Starting a webMethods Broker Server” on
page 61 for instructions.

Note: Whenever you stop the Broker Server, you will lose volatile documents in all
queues.
2 Make a copy of the contents of the Broker Server data directory, for example,
C:\webMethods\Broker\data\awbrokers65\default\Broker.qs.stor.
3 Restart the Broker Server. See “Stopping and Starting a webMethods Broker Server”
on page 61 for instructions.
For more information about exporting and using the broker_save and broker_load
commands, see “broker_save” on page 260 and “broker_load” on page 257.
Using the ADL Export/Import Feature of the Broker

Administrator to Copy
This section describes how to copy Broker Server information using the ADL
export/import feature that is available through the Broker Administrator. Using the
export/import feature, you can export just Broker Server information, Broker Server and
Broker information, or just Broker information as an ActiveWorks Definition Language
(ADL) file.
To copy Broker Server information using ADL Export/Import feature

2 From the Navigation panel, select the Broker Server from which you will copy
configuration information.
3 On the Broker Server Information page, click Export to File.
4 Select the Export Broker Server Configuration check box to export SSL configuration,
access control list, and logging setup information from the Broker.
5 If you want to export Broker configuration information, select the Export Broker
Configuration check box.
6 In the File format field, select the format you want to be used for the configuration file.
See “File Formats for Saving ADL Files” on page 81.
7 Click Proceed to Step 2.
8 If you also want to export Document Type, Client Group, or Client information, select that
information now.

Select... To...
Export Document Types Export indicated number of document types from the
selected Broker.
Export Client Groups Export indicated number of client groups from the selected
Broker.
Export Clients Export indicated number of clients from the selected Broker.
a To select a subset of any of these options, click Change Selection.

b By default, Document Type, Client Group, or Client information are all selected for
export. Click the check boxes of the elements you do not want to export, then click
Submit Changes.
9 When you are finished selecting the Broker information to export, click Export to File.
The configuration is saved as an ActiveWorks Definition Language (ADL) file and
then compressed for downloading.
10 Download the configuration file by clicking Click here to download ADL Zip-File.
Note: If the information you are copying includes an SSL configuration, you are
prompted for the certificate file password.
Note: To unzip the error log file on Windows systems, you can use any archive utility
available for Windows. On UNIX systems, use the Gzip data compression program.
Note: If you are copying Broker Server information to an ADL file for backup
purposes, you can stop here.
11 Open the Broker Server Information page of the target Broker Server.
12 Click Import From File.
13 In the Filename field, enter the path and name of the .adl file or click Browse to navigate
to the .adl file.
14 Click Upload.

15 Select one or more of the options in the What to Import Step 2 dialog box.
Select... To...
Overwrite webMethods Import and overwrite existing Broker Server SSL

Broker Server configuration configuration and logging setup information to
selected Broker Server.
Overwrite Broker Import and overwrite existing Broker description.
configuration
Make it the default Broker Make the selected Broker the default.
If the configuration does not contain information of a certain type (for example,
Broker Server configuration), that option is unavailable.
16 Click Proceed to Step 3.
17 Select one or more of the options in the What to Import Step 3 dialog box.
Select... To...
Overwrite/create Document Import (and overwrite) existing document types into

Types the selected Broker.
Overwrite/create Client Import client groups into the selected Broker. This
Groups option merges existing client groups or creates new
ones.
Overwrite/create Clients Import clients into the selected Broker.
To select a subset of any of these options, click Change Selection. By default, all
elements of each option are selected for import. Clear the check boxes of the elements
you do not want to import, then click Submit Changes.
18 Click Import from File.
Note: If the import file contains a new SSL configuration, you may need to stop and
restart the Broker Server for the configuration to take effect. If the import file does not
contain the password for the certificate file, you are prompted for it. For more
information, see “Backing up Broker SSL Certificate Files” on page 89.
Important! The Import from File option divides large files into 2MB pieces. The pieces are
then imported sequentially to the Broker and reassembled. If an error occurs during
this process, some document types may still be loaded; that is, the file may be
partially loaded if there is an error and the Broker is left in a partially updated state.

File Formats for Saving ADL Files
File Formats for Saving ADL Files

ADL (ActiveWorks Definition Language) is an ASCII file format that webMethods Broker
uses to export its configuration information in external files. When you name the ADL
files, you must save them with “.adl” file extension. You can save ADL files from either
Broker Administrator or the command line tool.
You can save ADL files in two file formats. This feature is useful if you use the
webMethods Broker system in a language that takes advantage of an extended character
set (greater than 256 characters). The two file formats are:
File Format Description
Platform independent Includes Unicode escape characters (the default). The file
can be exported to other hosts without regard to machine
type or language.
Native (locally editable) Does not include Unicode escape characters. The file can
only be used on hosts of the same type and which use the
same language and encoding.
The use of Unicode escape characters makes it possible to export Broker and Broker
Server configuration among hosts that use different languages (and sometimes to
different types of host machine that use the same language). If you want to read or edit
the configuration file, however, the escape characters can make such tasks difficult.
If your language uses an expanded character set and you want to read or edit the Broker
or Broker Server configuration file, you should save it in native format. Doing so means
that you can only export the file to another host of the same type that supports the same
language as the one on which you created the file.
In English, or other languages that do not use an extended character set, always use the
platform-independent file format to save an export file.

Saving and Restoring System Configuration Data

To save and restore system configuration data, webMethods Broker provides three
different methods:
Method Use this method for...
1 Export/Import of Broker Server and Point-in time recovery of Broker and

Broker configuration data using ADL Broker Server configuration data.
files.
2 Back up and restore of the Broker Disaster recovery of Broker and Broker
Server configuration data storage Server configuration data.
using the Broker Server's backup and
restore features. Note: This is the recommended method.
3 Back up and restore of the Broker Disaster recovery of Broker and Broker
Server's combined data storage using Server configuration data when using
the file system's copy command. combined data storage.
Backing Up and Restoring System Configuration Using ADL

You can use the ADL export/import feature to accomplish point-in-time recovery. That is,
you can recover Broker and Broker Server configuration data to a specific point in time
where you are restoring the data back to when you initially saved the ADL file.
Note: You should save copies of the following:

Both the Broker and Broker Server configuration files in a location other than a
webMethods Broker host. That way, if the disks ever fail on the Broker Server host,
the back up files are still safe.
The awbroker.cfg residing in the Broker Server's data directory on a regular basis.
For point-in-time recovery, you should export your system configuration before you
make any configuration changes.

Backing Up and Restoring System Configuration Using ADL
Backing Up By Exporting System Configuration

Exporting the configuration of a single Broker is a simple matter. Exporting a
webMethods Broker system with multiple territories and territory gateways is more
complex, requiring multiple steps. In the sample configuration illustrated below, Brokers
A and B are members of Territory 1, and both reside on the Broker Server Alpha. Brokers
C and D are members of Territory 2, and both reside on the Broker Server Beta. Brokers B
and C form a gateway between the two territories.
Sample Backup Configuration
Broker B Broker D
Broker A Broker C
Territory 1 on Broker Server Alpha Territory 2 on Broker Server Beta
To export the entire system, you must export a separate configuration file for each Broker
and each Broker Server. Therefore, in the sample configuration in above, there must be
configuration files for each of the following:
Broker Server Alpha
Broker Server Beta
Broker A
Broker B
Broker C
Broker D
Exporting Broker Server Configuration Using ADL

See “Using the ADL Export/Import Feature of the Broker Administrator to Copy” on
page 78 for instructions on exporting Broker Server and Broker information to an ADL
file. Repeat the procedure for each Broker in your webMethods system configuration.
Exporting Broker Server Configuration from the Command Line

If you prefer to work from the command line, use the broker_save command line tool to
save a configuration file for each Broker Server and each Broker in the configuration. For
more information about exporting and using the broker_save and broker_load
commands, see “Using Broker Command Line Tools to Copy” on page 77. For more
information about the broker_save command, see “broker_save” on page 260.

To save the Broker Server data directory using broker_save
queues.
2 Make a copy of the contents of the Broker Server data directory, for example,
C:\webMethods\Broker\data\awbrokers65\default\Broker.qs.stor.
For more information about the broker_save command line tool, see “broker_save” on
page 260.
Restoring System Configuration Through ADL Import

For point-in-time recovery, you should import a previously saved ADL file following the
order described in this section. If you want to change the names of Broker Servers,
Brokers, or territories before importing the system, you must edit the configuration files
manually to change each instance of the names you want to change.
Note: If you run webMethods Broker in a language that uses an extended character set,
the Unicode escape characters may make configuration files difficult to read. See
“Configuring webMethods Broker Servers from the Command Line” on page 55.
To restore a system configuration using ADL import
1 For each Broker Server that you are going to restore the system configuration for,
import the Broker Server ADL file using one of these tools:
Tool: Described in:
Broker Administrator “Using the Clipboard Feature of the Broker Administrator

to Copy” on page 77
broker_load program “broker_load” on page 257

Backing Up and Restoring System Configuration Data Storage
2 For each Broker that you are going to restore the system configuration for, import the
Broker ADL file using one of these tools:
Tool: Described in:
Broker Administrator “Using the Clipboard Feature of the Broker Administrator

to Copy” on page 77
broker_load program “broker_load” on page 257
If the configuration contains any gateways, take note of warnings that indicate that
the other side of the gateway is not yet available.
3 Re-import any Broker configuration files that gave warnings during the previous
step, using the same order as before.
You should not receive any warnings during this step.

Direct backup of the Broker Server configuration data storage offers a quick way to
restore a Broker Server in the event of a configuration data storage failure. webMethods
Broker provides a command line tool for you to back up the Broker Server's configuration
data storage without having to stop the Broker Server. A command line tool is also
provided for restoring a Broker Server's configuration data storage from a backup copy.
Important! You must have your Broker Server configured with separate storage sessions in
order to use the Broker Server's online configuration data backup command line tool. This
is the default storage configuration for new installations of webMethods Broker 6.5. For
more information about the server_config create command line tool, see page 237.
When you backup your Broker Server's configuration data storage, you should save the
backup copy of the Broker Server configuration data storage in a location other than a
webMethods Broker host. That way, if the disks ever fail on the Broker Server host, the
backup copies are still safe. You should also save a copy of the awbroker.cfg residing in
the Broker Server's data directory on a regular basis.
Note: For disaster recovery, you should back up your Broker Server's configuration data
storage immediately after you have made any configuration changes.

Backing Up System Configuration Data Storage

Similar to exporting Broker configuration using ADL, backing up the configuration data
storage of a single Broker Server is a simple matter. However, backing up a webMethods
Broker system with multiple territories and territory gateways is more complex, requiring
multiple steps. In the sample configuration illustrated below, Brokers A and B are
members of Territory 1, and both reside on the Broker Server Alpha. Brokers C and D are
members of Territory 2, and both reside on the Broker Server Beta. Brokers B and C form a
gateway between the two territories.
Sample Backup Configuration
Broker B Broker D
Broker A Broker C
Territory 1 on Broker Server Alpha Territory 2 on Broker Server Beta
To produce a consistent set of backups of the configuration data storage for the entire
system, you must back up each Broker Server. Therefore, in sample configuration in
above, you should back up the following:
Broker Server Alpha
Broker Server Beta
Important! It may be impractical for you to back up your entire system if you have many
Broker Servers. However, it is critically important that you back up all of the Broker
Servers that have Brokers in a same territory immediately after you have made a
configuration change to one or more Brokers in that territory.
Backing Up from the Command Line

For disaster recovery, use the server_conf_backup command line tool to back up the
Broker Server configuration data storage. For more information about the command, see
“server_conf_backup” on page 232. Backup each Broker Server in your webMethods
system configuration.
Note: The server_conf_backup command line tool is an online backup tool designed to
be used with a running Broker Server.

Restoring System Configuration Using the

server_conf_restore Command Line Tool
Use the server_conf_restore command line tool to restore the Broker Server
configuration data storage due to storage corruption issues. Repeat the procedure for each
Broker Server in your webMethods system that needs to be restored. For more
information about the restore command line tool, see “server_conf_restore” on page 234.
To restore a system configuration data storage for disaster recovery

2 Remove the Broker Server's run-time data storage using the file system command.
You must remove the existing run-time data files ending in “.qs.stor” and “.qs.log”
(not the .qs file).
3 Run the server_conf_restore command line tool to restore the Broker Server's
configuration data storage run-time data from a backup. On UNIX, you will need to
change the permissions on the restored files.
4 Restart the Broker Server.
5 Repeat the procedure for each Broker Server in your webMethods system that needs
to be restored.
Important! Regardless of the condition of the Broker Server's run-time data (corrupted or
uncorrupted) storage, the backup/restore feature only aids in the recovery from Broker
Server's configuration data storage corruption. It is highly risky to restore the Broker
Server's configuration data storage without removing its run-time data storage because
of potential data inconsistencies between the two storage sessions. You should remove
the Broker Server's run-time data storage either before running the
server_conf_restore command or after running the server_conf_restore command
and before restarting the Broker Server.

Backing up and Restoring Combined Broker Server Storage

If you configure your Broker Server to use the combined storage session and your Broker
Server has no Broker that belongs to a territory, you can back up the combined storage
using the file system's copy command.
Important! Always stop the Broker Server before backing up; otherwise, the backup could
be corrupted. Refer to section “Stopping and Starting a webMethods Broker Server” on
page 61.
To backup the Broker Server data directory for combined storage session
queues.
2 Make a copy of the contents of the Broker Server data directory, for example:
C:\webMethods\Broker\data\awbrokers65\default\Broker.qs.stor
Note: Backing up the Broker Server files when there are guaranteed documents in
client queues is not recommended because these documents will be re-sent again
when the data files are restored.
To restore the Broker Server data directory for combined storage session
queues.
2 Copy the backup files of the Broker Server back to the Broker Server data directory,
for example, C:\webMethods\Broker\data\awbrokers65\default\Broker.qs.stor

Backing up Broker SSL Certificate Files
Note: The use of the file system copy command to back up and restore Broker Server data
storage is not recommended. If the Broker Server configuration data storage backup and
restore are important to your operation, you should consider upgrading to a separate
storage session configuration.
There is no direct path to convert from a combined storage to a separate storage
configuration. If you would like to take advantage of the Broker Server online
configuration data storage backup and restore feature, you must create a new Broker
Server with separate configuration and run-time data storage sessions and populate the
new Broker Server with ADL files exported from the existing Broker Server. For more
information, see the webMethods Broker Upgrade Guides.
Backing up Broker SSL Certificate Files

While the Broker Server data directory contains configuration and statistics information
for the Broker Server and its Brokers, the directory does not necessarily contain the
certificate file used for SSL support. When you back up Broker Server data directories on
your host, it is also good practice to back up the certificate files that those Broker Servers
use. For this reason, webMethods recommends that you place the Broker Server’s
certificate file into the data directory. For more information about certificate files, see
“Creating and Managing SSL Certificate Files” on page 183.


PART III
Client Administration
Managing Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Managing Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Managing Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113

CHAPTER 6
Managing Client Groups
Understanding Client Group Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Displaying Client Group Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Creating and Configuring a Client Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Deleting a Client Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

CHAPTER 6 Managing Client Groups
Understanding Client Group Properties

Client groups have certain properties that determine how Broker clients within the client
group interact with the Broker. The properties you set when creating and configuring
client groups are shown below.
Property Description
Client Group description A one-line description of the client group, to be displayed in
Broker Administrator main window.
Broker Client lifecycle Determines what the Broker does with a Broker client’s state
when the Broker client disconnects. There are two types of
life cycles:
Explicit destroy and
Destroy on disconnect.
See “Life Cycle Properties” on page 95.
Client queue storage type Determines how safe the documents in a Broker client’s
queue are. Storage type also affects how quickly a Broker
can process documents. See “Client Queue Storage Types”
on page 95.
Encryption level None
U.S. Domestic, which is 128-bit/1024-bit encryption
U.S. Export, which is 40-bit/512-bit encryption

Access control list Lists the digital certificates a client may use to connect to a
Broker. See Chapter 11, “Managing Broker Security.”
Can publish types Lists all document types that Broker clients in the specified
client group can publish (or deliver). See “Assigning “Can
Publish” and “Can Subscribe” Permissions” on page 100.
Can subscribe types Lists all document types that Broker clients in the client
group can subscribe to (or receive deliveries from). See
“Assigning “Can Publish” and “Can Subscribe”
Permissions” on page 100.
Log publish types Lists all document types that Broker clients in the client
group can log when published. See “Assigning Log Publish
and Log Acknowledge Types” on page 102.
Log acknowledge types Lists all document types that Broker clients in the client
group can log when received. See “Assigning Log Publish
and Log Acknowledge Types” on page 102.

Understanding Client Group Properties
Life Cycle Properties

The life cycle determines if the Broker keeps information about the Broker client’s state
when the Broker client disconnects from the Broker or when the Broker restarts. The two
types of life cycles are shown below.
Life Cycle Description

Explicit destroy The state of a Broker client exists until it is destroyed by a
program using the Broker client. The Broker remembers the
Broker client’s state across connections and Broker Server
restarts. Use the Explicit destroy life cycle for applications that
need to maintain state information in the Broker between
connections.
For example, a webMethods Broker dbAdapter uses the
explicit destroy life cycle so that documents that update the
database are not lost if the adapter is not running. When the
dbAdapter is not running, the Broker queues documents for it;
the dbAdapter retrieves the documents when it restarts.
Destroy on disconnect The state of a Broker client exists for the duration of the Broker
client’s connection to the Broker. The Broker automatically
deletes the client state when the connection breaks. Use Destroy
on disconnect for applications that do not need to maintain any
state in the Broker between connections. For example, Broker
Administrator uses this kind of client connection when it is
running.
Client Queue Storage Types

Because all documents flow through Brokers, administrators need to make performance
trade-offs by selecting the storage mechanism the Broker uses for queueing documents.
The safer the storage mechanism, the slower the performance. Storage types determine
how safe and reliable the stored document is and how quickly a document is placed in
storage.
You can assign a client queue storage type only at the time you create a client group. You
cannot change the client queue storage type. The storage types are shown below.

Queue
Storage Type Description
Guaranteed The safest, but slowest type of storage. This storage type is suited for
storage documents that you cannot afford to lose. Documents are written to
disk using a logged commit. Guaranteed storage has a fixed,
pre-allocated size that can only be changed while the Broker is stopped;
how large a portion depends on the document flow and size of
documents. The default guaranteed storage size is 32MB per transaction
and 512MB. You can increase the storage size by adding new storage
files, see “server_config storage” on page 248.
Persistent Broker versions 5.0 through 6.5 automatically upgrade all Persistent
storage documents to Guaranteed; all Persistent documents are treated as if
they are Guaranteed.
Volatile The least safe but fastest type of storage. This storage type is suited for
storage documents that have a short life or are not critical. Documents are not
written to disk; they are only stored in memory. All documents of a
volatile document type and documents in a volatile client queue are lost
when the Broker is shut down or when the computer restarts.
Maximum Storage File Size

The default installation creates a log file of 32MB and a single storage file of 512MB. The
server_config program allows you to increase the size of the log file and add up to 61
additional storage files. See the table below for storage file limitations.
Factors Limitations
Document size Limited to the lesser of:
1GB with a transaction size of 1GB
The size of the log file, which can be increased using the
server_config program (see “server_config storage” on
page 248 for more information)
The amount of virtual memory available on the Broker host
(divided by 3 due to the internal buffering)
Total storage Dependent on Broker hardware
available

Displaying Client Group Activity
Client Queue Storage Versus Document Type Storage

When a document is published, the Broker normally puts it directly into the client’s
queue. However, first it makes an initial allocation according to the document’s storage
type. The document’s storage type can be Volatile, Persistent or Guaranteed. When the
Broker moves a document into the client queue, the document’s storage type may be
altered. This alteration occurs for two reasons:
Client queues support simultaneous storage of only two of the three document
storage types:
Volatile only
Volatile and/or Guaranteed
The Broker upgrades Persistent documents to Guaranteed Storage
Because client queues support only two types of storage at one time, you need to assign
life cycle and storage type properties to a client group with the understanding that a
document’s storage type may be overridden by the client queue’s storage type.
All documents going into a volatile client queue are placed in Volatile storage. Even if a
document type has Guaranteed storage properties assigned to it, the document’s storage
property changes to Volatile when the client queue is volatile.
All non-Volatile documents going into a non-Volatile queue are placed into Guaranteed
storage.
Information on the type of storage used for combinations of document type and client
queue storage is summarized below.
Client Queue Storage Type

Document Storage Type Volatile Persistent or Guaranteed
Volatile Volatile Volatile
Persistent or Guaranteed Volatile Guaranteed
Displaying Client Group Activity

You can display life cycle and client queue properties of a client group and view the
publishing activity of its Broker clients. You can analyze how often and when Broker
clients in a group publish documents.
To display Client Group activity

2 From the Navigation panel, under the appropriate Broker Server and Broker, click
Client Groups.

The Client Groups on Broker page appears, displaying the list of client groups and
their descriptions. The information and statistics in Client Groups on Broker page are
as follows.
Client Group Name of the client group

Queue Type Storage type of the client queue
Lifecycle Life cycle type of the client group
Description A one-line description of the client group
Created Date and time the client group was created
3 Click a client group name to view additional information and statistics. The
information and statistics on the Client Group Information page are as follows:
Description One-line description of the client group

Lifecycle life cycle type of the client group
Queue type Storage type of the client queue
Created Date and time the client group was created
Last modified Date and time the client group was last modified
System defined Whether or not the client group is system defined
Encryption level The level of encryption. Values are None, U.S. Export, and U.S.
Domestic
Access label required If the value is Yes, a client requires an access label to connect to
this client group
Total documents Total number of documents that Broker clients in this group
published have published
Last published Date and time a Broker client in this group last published a
document
Access control Lists the digital certificates a client may use to connect to a
Broker. See Chapter 11, “Managing Broker Security.”
Can publish types Displays the number of document types that Broker clients in
the specified client group can publish (or deliver). Click this
number to list all document types.
Can subscribe types Displays the number of document types that Broker clients in
the specified client group can subscribe to (or receive
deliveries from). Click this number to list all document types.

Creating and Configuring a Client Group
Log publish types Displays the number of document types that Broker clients in
the client group can log when published. Click this number to
list all document types. See “Assigning Log Publish and Log
Acknowledge Types” on page 102.
Log acknowledge Displays the number of document types that Broker clients in
types the client group can log when received. Click this number to
list all document types. See “Assigning Log Publish and Log
Acknowledge Types” on page 102.

There are four general steps to follow when creating and configuring a client group:
1 Create a client group by assigning a name, life cycle, and client a queue storage type
to the client group. See “Creating a Client Group” on page 99 for instructions.
Optionally, provide a brief description of the client group, to be displayed in the
Broker Information page.
2 Determine the document types to which the client group can publish and subscribe.
See “Assigning “Can Publish” and “Can Subscribe” Permissions” on page 100 for
instructions.
3 Optionally, set required encryption level.
4 Set access controls for the client group. See “Setting Up Client Group Access Control
Lists” on page 177).
Creating a Client Group
To create a Client Group

Client Groups.
3 From the Client Groups page, click Create a New Client Group.
4 In the Client Group Name field, enter the name of the client group.
5 In the Client Group Description field, type a brief description of the client group.
6 Select the life cycle you want the Broker clients in the group to have.

If you select Destroy on Disconnect, the queue storage type is automatically Volatile. If
you select Explicit Destroy, you need to select the queue storage type. See “Life Cycle
Properties” on page 95 for details about client group life cycle properties.
7 Select the queue storage type (if you selected Explicit Destroy life cycle) from Queue
Storage Type field.
8 Click Create.
Once the client group is created, you can configure Can Publish and Can Subscribe
permissions. See “Assigning “Can Publish” and “Can Subscribe” Permissions” below.
Assigning “Can Publish” and “Can Subscribe” Permissions

You can determine which document types Broker clients in a client group can publish and
subscribe to by assigning Can Publish and Can Subscribe permission to specific document
types.
Note: A Broker delivers a document only to Broker clients that have subscribe permission
to it. A delivered document is addressed to just one Broker client.
Adding “Can Publish” and “Can Subscribe” Permission

This section describes how to set publish and subscribe permissions in a document type.
To set these permissions, you add document types to the client group’s Can Publish and
Can Subscribe lists.
To add document types to a client group’s Can Publish list

Client Groups.
3 On the Client Groups page, click the name of the client group whose Can Publish list
you want to update.
4 On the client group information page, click the linked value to the right of Can publish
types.
The Can Publish Document Types page lists all document types to which Broker
clients in the client group can publish.
5 To add additional document types, click Add Can Publish Document Types.
The Add Document Types page displays all document types known to the Broker that
are not already in the Can Publish Document Types list.

6 Select the document types you want to add, then click Add.
The document types you selected now appear in the Can Publish Document Types list.
To add document types to a client group’s Can Subscribe list

Client Groups.
3 From the Client Groups page, click the name of the client group whose Can Subscribe
list you want to update.
4 From the client information page, click the linked value to the right of Can subscribe
types.
The Can Subscribe Document Types page lists all document types to which clients in
the client group can subscribe.
5 To add additional document types, click Add Can Subscribe Document Types.
The Add Document Types page displays all document types known to the Broker that
are not already in the Can Subscribe Document Types list.
The document types you selected now appear in the Can Subscribe Document Types list.
Removing Can Publish and Can Subscribe Permission
To remove a document type from a Client Group’s Can Publish and Can Subscribe lists

Client Groups.
3 From the Client Groups page, click the name of the client group whose Can Publish or
Can Subscribe list you want to update.
To remove a document type from the Can Publish list, click the linked value to the
right of Can Publish types. Then click Delete Can Publish Document Types.
To remove a document type from the Can Subscribe list, click the linked value to
the right of Can Subscribe types. Then click Delete Can Subscribe Document Types.
5 In the Delete Document Types list, select the document type(s) you want to remove.
6 Click Delete.

Assigning Log Publish and Log Acknowledge Types

You can define which document types Broker clients can log by assigning Log Publish and
Log Acknowledge permission to specific document types.
To add document types to a client group’s Log Publish Document Types lists

Client Groups.
3 From the Client Groups page, click the name of the client group whose Log Publish
Document Types list you want to update.
4 On the client group information page, click the linked value to the right of Log publish
types.
The Log Publish Document Types page then displays all document types that the
client group will log.
5 To add additional document types, click Add Log Publish Document Types.
The Add Document Types page then displays all document types known to the
Broker that are not already in the Log Publish Document Types list.
The document types you selected now appear in the Log Publish Document Types list.
.
To add document types to a client group’s Log Acknowledge Document Types lists

Client Groups.
3 From the Client Groups page, click the name of the client group whose Log
Acknowledge Document Types list you want to update.
4 Click the linked value to the right of Log acknowledge types.
All document types which the client group will acknowledge are listed.
5 To add additional document types, click Add Log Acknowledge Document Types.
The Add Document Types page appears. This page displays all document types
known to the Broker that are not already in the Log Acknowledge Document Types list.
6 Select the document types you want to add and then click Add.
The document types you selected now appear in the Log Acknowledge Document Types
list.

Changing a Client Group Description

You can create or modify a brief description of the client group. The description is
displayed in the Client Group Information page.
To add a Client Group description

Client Groups.
3 On the Client Groups page, click the name of the client group whose description you
want to update.
4 On the Client Group information page, click Change Description.
5 On the Change Description page, enter a new description in the Description field.
You can also provide a client group description at the time you create the client group,
as discussed in “Creating a Client Group” on page 99.
Setting the Client Group Encryption Level

You can secure data transmission between client groups and Brokers by setting the
encryption level to U.S. Domestic or U.S. Export.
To set the encryption level for the Client Group, follow these steps:
Client Groups.
2 On the Client Groups page, click the name of the client group whose encryption you
want to change.
3 On the Client Group information page, click Change Encryption Level.
4 Select one of the following options:
None

Deleting a Client Group

Use Broker Administrator to delete a client group. Keep in mind that you cannot undo a
client group deletion.
Note: Each client group’s document folder contains client groups that come with the
webMethods Broker system: adapters, admin, and accessLabelAdapter. You cannot
delete these client groups. The Delete option is disabled when these client groups are
selected.
To delete a Client Group

Client Groups.
3 On the Client Groups page, click Delete Client Groups.
4 Select the client group you want to delete and then click Delete.
5 In the confirmation dialog box, click OK.
Note: You cannot delete a client group if Broker clients in the group are connected to the
Broker. You must delete the Broker clients before deleting the group.

CHAPTER 7
Managing Document Types
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
About Managing Document Types in a Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Displaying the Document Types in a Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Editing Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Displaying Subscription Filter Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

C H A P T E R 7 M a n a g i n g D o c u m e n t Ty p e s
Overview
This chapter describes how to manage document types and measure system activity. For a
brief overview of document types, see “Document Types” on page 19. For more
information about developing document types and document folders, refer to Publish-
Subscribe Developer’s Guide.
About Managing Document Types in a Broker

As a System Administrator, there are a variety of reasons for you to view and manage the
document types in a Broker. For example, in order to understand the purpose of a
particular document, you can view the document types set up in the Broker, or you can
browse a document type’s data fields to learn more about the document.
Another reason to view document types in a Broker is to measure system activity. There
are several ways in which you can measure system activity, for example, you can:
Watch how Broker clients use document types
Keep track of how often a document type is used
Publish documents and check the document type’s publish and retrieve statistics to
ensure that the Broker client subscriber actually received documents
Note: The maximum number of document types that a Broker can support is 65533.
Displaying the Document Types in a Broker

You can display the list of document types stored on the Broker to verify that the
document types that a Broker client needs are present. Or, if you do not know what a
particular Broker is used for, browsing the Broker’s list of document type names and their
data fields is helpful.
To display the list of a Broker’s document types

Document Types.

Displaying the Document Types in a Broker
The Document Types page lists the following information about all document types
that exist in the current Broker.
Document Folder/Type Name of the document type or document folder.

Storage Type Storage type of the document type.
Description A brief description of the document type.
Created Date and time the document type was created.
3 On the Document Types page, click the name of the folder/document type for which
you want to display document type information. If the document type is stored in a
folder, continue clicking until you reach the document type you want to display.
The Document Type Information page displays the following information.
Description A brief description of the document type. See “Document

Type Description” on page 108.
Storage Type The document type’s storage type. See “Document Type
Storage Types” on page 109.
Created The date and time the document type was created.
Last Modified The date and time the document type was last modified.
System Defined Whether or not the document type is system defined.
Total Documents Total number of times this document type has been
Published published.
Last published Date and time this document was published.
Subscriptions Number of subscriptions that Broker clients in the Broker
have registered for the document type.
Forwards received The number of documents of this type received from a
remote Broker in the same territory.
Last forward The date and time a document was last forwarded from a
remote Broker in the same territory.
Time to live Attribute of a document type that determines how long a
Broker keeps a document. See “Document Time to Live” on
page 109”.

Validation Full. All fields must be defined in the document type and
all fields must match the document type definition. New
fields cannot be created in the published document.
Open. Fields that are defined in the document type must
match the document type definition. Fields can be
present in the published document and not be checked.
None. No validation for published documents.
See “Document Type Validation” on page 110.
Fields The data fields of a document. See “Data Field Information”
on page 111.
Infosets For pre-6.0 Brokers only. The infosets that help to define the
use of the document type.
Editing Document Types

Although you create and edit document types using Developer, there are some
management tasks you can perform through the Broker Administrator. The follow
sections describe how to edit document type information using the Broker Administrator.
Note: To perform any editing task in the Broker Administrator, you must have the
appropriate permissions. See “Setting Up Broker Administrator Permissions” on page 32
Document Type Description
To change the Document Type description

Document Types.
3 From the Document Types page, click the document type whose description you want
to change. If the document type is stored in a folder, continue clicking until you reach
the document type you want to change.
4 On the Document Type doctype page, click Change Description.
5 On the Change Description page, enter a new description in the Description field.

Editing Document Types
Document Type Storage Types

A document type’s storage type, which you set using Developer, determines how safely
and reliably the document is stored by the Broker. The two storage types a document type
can have are Volatile and Guaranteed. For more information about storage types, see
“Client Queue Storage Types” on page 95. For information about how to assign storage
properties to a document type, refer to the webMethods Developer User’s Guide.
A document’s storage type can be overridden by the storage type of a client’s queue. For
more information, see “Client Queue Storage Versus Document Type Storage” on
page 97.
Note: The Broker Server automatically upgrades Persistent storage types to Guaranteed.
Document Time to Live

The Time to Live (TTL) attribute of a document type determines how long the Broker
keeps a document. The current TTL setting applies to all documents of that type stored in
the Broker. A TTL value of Forever, the default, means the Broker will never delete the
document before a Broker client retrieves it. You can also set the number of seconds from
the time the document is published until the Broker deletes it. The document is only
deleted if it is still in the incoming queue or a client queue when its TTL expires. For
example, if you set the TTL of a document type to 30, documents of that type that remain
in the Broker for more than 30 seconds are deleted.
Note that the TTL applies to the total time a document spends in the Broker.
The TTL can be useful for documents containing data that is updated regularly, such as
stock quotes. If a document is generated for a quote every 20 seconds, the TTL can be set
to 20 seconds. If a Broker client does not retrieve the quote after 20 seconds, then it might
as well be deleted because a newer value will arrive soon.
The current implementation of TTL does not actively check if a document has exceeded its
TTL. A document’s TTL is checked only when a document is retrieved from a Broker.
Reducing the TTL of a document type does not have an immediate effect on documents
already in the incoming or client queues. If a Broker client is actively retrieving
documents from its queue, the Broker deletes from the top of the queue those documents
that have expired TTLs.
To change the Document Type’s Time to Live attribute

Document Types.

3 On the Document Types page, click the document type whose time to live attribute
you want to change. If the document type is stored in a folder, continue clicking until
you reach the document type you want to change.
4 On the Document Type doctype page, click Change Time to Live.
5 On the Change Time to Live page, in the Time to Live field, enter the number of seconds
you want the Broker to keep a document. Enter “0” if you do not want the Broker to
delete the document before a Broker client retrieves it.
Document Type Validation

The document type validation level determines if the Broker will prevent or permit
publication of undefined document type fields.
When a Broker receives a document, it checks or validates the information in the
document’s document type field against the document type definition. The Broker will
accept or deny the document based on the outcome of the validation.
There are three levels of validation the Broker can perform:
Full. The default setting. All fields must be defined in the document type and all fields
must match the document type definition. New fields cannot be created in the
published document.
Note: This is the strictest form of validation and can affect performance because the
Broker must check each and every document type field.
Open. Fields that are defined in the document type must match the document type
definition. Fields can be present in the published document and not be checked.
None. No validation for published documents.
Using the Broker Administrator you can change the level of validation or disable
validation for published documents altogether.
To change the validation level

Document Types.
3 On the Document Types page, click the document type whose validation level you
want to change. If the document type is stored in a folder, continue clicking until you
reach the document type you want to change.
4 On the Document Type doctype page, click Change Validation.

Displaying Subscription Filter Strings
5 On the Change Validation page, select Full, Open, or None.

Data Field Information

You can view the data fields of a document type to learn more about what the document
type does. When a Broker client publishes a document, it fills the document fields with the
data it wants distributed. Subscribers read the data from the fields for subsequent use.
Although you can use Broker Administrator to determine information about a document
type, you cannot use it to create one. To create document types, you must use the
Developer. For more information, see the webMethods Developer User’s Guide.
Displaying Subscription Filter Strings

From Broker Administrator you can view the subscription filter strings associated with
document types. Broker Administrator must be connected to the Broker Server whose
client application communicates with adapters.
To display subscription filter strings

2 From the Navigation panel, under the appropriate Broker Server and Broker, click the
name of the client whose subscription filter string you want to display.
3 In the Client Information table, click the linked value to the right of Subscriptions to
display the Subscriptions on Client page, Client represents the name of the Broker
client.
The Subscriptions page displays a list of the Broker client’s subscriptions. The
subscription filters appear in the Filters column.
If you want to modify a filter string for a specified document type, you must do so using
Developer. Refer to the webMethods Developer User’s Guide for instructions.


CHAPTER 8
Managing Broker Clients
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114
Viewing Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114
Managing Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Monitoring Broker Client Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Controlling Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

CHAPTER 8 Managing Broker Clients
Overview
This chapter describes how to view, manage, and monitor Broker clients. For information
about creating and naming Broker clients, refer to the appropriate programming interface
manual.
Viewing Broker Clients

A client program creates one or more Broker clients to publish or retrieve documents. For
example, a network monitoring application might create a Broker client to publish
documents that represent network transmission errors. A network management
application might create a Broker client to subscribe to these network error documents. If
the number of network errors documents retrieved reaches a critical threshold, the
management application might create a different Broker client and use it to publish
statistics about the network failure.
Document-based client applications are de-coupled from one another because they
generate and receive documents through the Broker Server. When your client program
creates a Broker client, it is actually establishing a connection between your application
and a Broker running on the local host or some host on the network.
You can view Broker client activity and statistical information using the Broker
Administrator.
Displaying Broker Clients
To display the clients on a Broker

2 From the Navigation panel, under the Broker whose clients you want to display, click
Clients.
The Clients page lists all clients that are on the Broker and for each one, includes the
following information.
Client ID The Broker client’s unique ID. Either the user or the Broker assigns
this ID at the time the Broker client is created.
Application Name The name of the application that describes the Broker Client. The
user assigns this name at the time the Broker client is created.
Group The client group the Broker client belongs to.

Connected The Broker’s connection status:

yes The Broker client is currently connected to the Broker.
no The Broker client is not currently connected to the
Broker.
Using SSL The client’s SSL status:
yes All sessions for this client use SSL.
no No sessions for this client use SSL.
Documents in Number of documents in the queue. Click this entry to view the
Queue latest statistics on published, retrieved, and delivered documents.
For more information, see “Displaying Broker Client Behavior” on
page 124.
Client Filters
You can apply filters to the list of clients on the Clients page. In the Client Filter pulldown,
select a filter type, then click Refresh Display to update the screen with the new filter
settings.
The default filters are described on page 33. You can also create a custom filter by clicking
Modify Filters.
To create a custom filter

2 From the Navigation panel, under Settings, click Client Filters. (You can also access this
page by clicking Modify Filters from a Broker’s Clients page.)
3 On the Client Filters page, click Add User Defined Client Filter.
4 In the User Client Filters box, enter a name for the new filter, then create the filter
rules.
The following table identifies the information that you can filter on for each client.
Client Information Description
Client ID Filter by the Broker client’s unique ID.

Application Name Filter by the name of the application that describes the Broker
client.

Group Filter according to the client group to which the Broker client
belongs.
Connection Status Filter clients by connection status. You can filter clients that are
currently connected to the Broker, not connected, or both.
Tip! If you do not want to show clients with a particular substring, use the logical
negation operator symbol “!” in front of the filter rule. For example, if you do not
want to show clients from the XYZ client group, you would enter “!XYZ” in the Group
field.
You can create one or more filter rules for each client filter. Create a client filter with
multiple rules to show clients that contain all of the query terms. For example, you
can create a client filter to show only the clients that are an “IntegrationServer”
application and belong to client group “Admin.”
Displaying Broker Client Information
To display the Broker client information

name of the client whose statistical information you want to display.
The Client Information page displays the following information.
ID The Broker client’s unique ID. Either the user or the Broker
assigns this ID at the time the Broker client is created.
Application Name The name of the application that describes the Broker client.
This name is assigned by the developer at the time the
Broker client is created.
Broker Displays the name of the Broker
Subscriptions Displays the number of subscriptions for the client.

Sessions If state sharing is enabled, the number of sessions that

currently share the Broker client’s state. If state sharing is
disabled, a disconnected client has a value of 0; a connected
client has a value of 1.
Click the number of sessions to view additional
information, such as:
Where the connection is from
The connections ID
Whether SSL is being used
Time and date of last activity
Time and date of creation

Documents in Queue Number of documents in the client queue that are ready for
the Broker client to retrieve. Clicking the linked value to the
right displays the Documents in Queue page, which
contains additional information about the queue, such as
when the last document was queued and the total number
of documents published since the client was created.
Shared Document Order Order in which documents will be processed.
publisher Specifies that events will be processed in the
order they were sent by the publisher. The
default is publisher.
none Specifies that the events will be processed in
no particular order
State Sharing The status of state sharing for the Broker client:
enabled State sharing is enabled.
disabled State sharing is disabled.
Created The date and time the Broker client was created.
Client Group The client group to which the Broker client belongs. Click
Client Group Properties to display the Client Group
Information window for this client group.
Infoset For pre-6.0 Brokers only.

Forced Reconnect For 5.x Brokers and later. Specifies whether a Broker client
can reconnect to a Broker even when (at least from the
Broker's perspective) a connection already exists. This might
happen if you disconnect the machine on which a Broker
client is running, then reconnect it. The Broker might not
recognize that the connection was broken. With Forced
Reconnect set to False, the Broker will reject the
reconnection request. With Forced Reconnect set to True,
the Broker will break the existing connection and create a
new one, allowing the client to reconnect.
Queue is Locked no The queue for the Broker client is open and
documents are flowing as normal.
yes The queue for the Broker client is locked.
Note that when a queue is locked, you cannot
delete the Broker client.
For information about queue management,
see the appropriate programming interface
manual.
Lock Held by Client ID The client ID that established the lock.
Lock Held by Client The session number of the locked client.
Session
Lock Held Since The duration of time the queue lock has been established.
Access Label If the client has an access label, the contents of the label.
User Name If SSL is enabled for the client, the distinguished name used
in the client’s certificate.
If a client is created on the Broker over an authenticated SSL
connection, the Broker records the client's owner along with
the client. The owner is identified by the combination of
User Name and Authenticator Name. Clients that have an
owner only allow future reconnection from processes that
authenticate as the same user.
Authenticator Name If SSL is enabled for the client, the distinguished name of the
Certification Authority that issued the certificate.

Displaying Documents in a Client Queue
To display a client queue

name of the client whose document queue you want to display.
The Documents in Queue page displays the latest statistics for documents published,
received, and delivered on the Broker client.
The Documents in Queue page displays the following information.
Client Queue Length The number of documents in the client queue that are ready
for the Broker client to retrieve.
Client Queue Size The size of the client queue in bytes.
Last Queued The last time a document was placed in the client queue.
Last Retrieved The time the Broker client last retrieved a document from its
queue.
Last Published The time the Broker client last published a document.
Highest Documents in A count of the most documents in the queue for the Broker
Queue client at one time, and the date and time on which it
occurred.
Recent Deliveries The number of documents the Broker client has recently
delivered.
Total Documents The total number of documents the Broker client has
Retrieved retrieved from its queue.
Total Documents The total number of documents the Broker client has
Published published.
Publish Sequence The sequence number of the last document published by the
Number Broker client. For information about sequence numbers, see
the appropriate programming interface manual.

Displaying the Subscriptions Page
To display information about subscriptions on the Broker client

name of the client whose subscription information you want to display.
The Subscriptions page displays all the Broker client subscriptions and contains the
following information.
ID The Broker client’s unique ID. Either the user or the Broker
assigns this ID at the time the Broker client is created.
Document Type Displays the document type names.
Filter Displays set subscription filters.
To learn how to delete a subscription from a Broker client, see “Disconnecting a Broker
Client” on page 125.
Displaying the Sessions Page
To display information about sessions on a Broker client

name of the client whose session information you want to display.
The Sessions page displays all the Broker client current sessions and contains the
information shown below.
Connected From The IP address of the machine and the port from which the
client program session is connected.
ID The session ID. This is a unique number, generated by the
Broker client.

Using SSL If Yes, the session connection is using SSL.

If No, the session connection is not using SSL.
For more information on SSL, see Chapter 11, “Managing
Broker Security.”
Last Activity The date and time the Broker client last made a request of the
Broker.
Created The date and time the Broker client session was created.
For information about a particular session, click that session in the list of sessions to open
the Session’s Information page. The Session’s Information page displays platform and
encryption information for the session you have selected.
The Platform Information table displays information that is set by the Broker client. You
cannot edit this information from Broker Administrator; you can change it only in the
client application program.
Adapter Language The programming language of the Broker API used to connect to
the Broker.
Adapter Language Version of the adapter language.
Version
Hardware Hardware on which the broker client runs.
OS Operating system on which the broker client runs.
The Sessions Information page contains the following encryption information.
Encryption The level of encryption and version number of the encryption

software.
Authentication The level of authentication and version number of the
encryption software.
User Name The distinguished name of the active client program.
Authenticator Name The distinguished name of the Certification Authority that
issued the certificate.

Managing Broker Clients

The following sections describe basic administration tasks you can perform on individual
Broker clients.
Managing Broker Sessions

A session represents a connection between an active client program and the Broker, which
publishes and subscribes to documents. A single client program can have multiple
sessions to the same Broker client or to different Broker clients. Typically, a client program
has just one session to one Broker client.
By default, the Broker allows only one active session per Broker client. In the case of client
groups with explicit destroy life cycles, the Broker client may not have any active sessions.
Broker clients can have multiple sessions if you set the shared state attribute when you
created the Broker client using the webMethods Broker API. The shared state feature
allows multiple sessions to share the Broker client’s state, its subscriptions, and document
queue. This is useful for improving the performance of adapters because it allows
document processing to be performed in parallel. Note that administrative operations on
a shared state Broker client will affect all sessions using that Broker client.
Disconnecting Broker Client Sessions

Disconnecting the Broker client breaks all active sessions to the Broker client, as does
destroying the Broker client.
To disconnect Broker client session

name of the client whose session you want to disconnect.
3 Click Disconnect One or More Sessions.
4 On the Disconnect Sessions page, select the check box of the session you want to
terminate.
5 Click Disconnect.
For more information about Broker client sessions and the shared-state feature, refer to
the appropriate programming interface manual.

Monitoring Broker Client Behavior
Managing Client Queues

Most client queue management tasks must be performed through a programming
interface. However, the Broker Administrator allows you to view and clear backed up or
stagnated documents in a client queue.
Clearing Documents in a Client Queue
Important! Use this option with care because it will delete documents that the Broker client
not yet processed. If multiple clients are sharing the same client state, invoking this
method can have far-reaching effects.
To clear a client queue

name of the client whose queue you want to clear.
3 In the Client Information table, click the linked entry to the right of Documents in Queue.
The Documents in Queue page displays client queue statistics. See “Displaying
Documents in a Client Queue” on page 119 for a description of each statistic.
4 Click Clear Client Queue.
5 In the confirmation dialog box, click OK.
Set Up Logging for Broker Clients and JMS Clients

If you want to log data for Broker clients, such as 6.1 workflows or 4.x Enterprise adapter
activations, or if you want to log messages form JMS clients, see the webMethods Integration
Platform Logging and Monitoring Guide.
Monitoring Broker Client Behavior

The Broker Administrator allows you to monitor the client document traffic through a
Broker. Monitoring this traffic can help you to determine how a Broker is being used and
if Broker clients are behaving normally.
Viewing the information displayed in the Documents in Queue page and Sessions page
allows you to pinpoint abnormal behavior and then take corrective action.
For example, you may discover that a Broker client is publishing more documents than
you expect, in which case, you may want to disconnect the Broker client or delete it
entirely. You may find that you need to delete a Broker client because the associated
application has been uninstalled or removed. Or, you may find that you should delete a

Broker client’s subscription to eliminate the unwanted delivery of a document from

another Broker client that is not functioning properly.
Displaying Broker Client Behavior

You can use the Documents in Queue and Sessions pages to see how a Broker is being
used and if Broker clients are behaving normally.
You can access the Documents in Queue and Sessions pages via the Client Information
page.
Controlling Clients
There may be times when you need to control a Broker client that is not behaving
normally. There are several methods you can use to control a Broker client, such as
removing a Broker client subscription, disconnecting one or more Broker client sessions,
or deleting a Broker client.
You may want to remove a Broker client’s subscription to stop the unwanted and
repeated delivery of a document from another out-of-control Broker client. You can
disconnect a misbehaving Broker client from the Broker without destroying its queue or
documents as long as it does not have a Destroy on Disconnect life cycle. You may want to
delete a Broker client, rather than just disconnecting it, if it did not disconnect from the
Broker when it should have. Deleting a Broker client always destroys its queue, regardless
of the life cycle type.
Removing a Broker Client Subscription

Use Broker Administrator to remove unwanted subscriptions from a Broker Client.
To remove a Broker client’s subscription

name of the client whose subscription you want to remove.
3 In the Client Information table, click the linked value to the right of Subscriptions.
4 Click Delete Subscriptions.
The Delete Subscriptions page displays a list of the Broker client’s subscriptions. Each
subscription is listed by a subscription ID, document type, and filter expression. Refer
to the appropriate interface programming manual for more information about
subscriptions.
5 Select the subscription(s) you want to remove and then click Remove.

Controlling Clients
If you have multiple subscriptions selected at the time you use this command, all of the
selected subscriptions are removed.
Disconnecting a Broker Client

You can disconnect a Broker client from the Broker by disconnecting all of its sessions. If
the Broker client has an Explicit Destroy life cycle, the Broker keeps the Broker client’s
state. If the Broker client has a Destroy on Disconnect life cycle, the Broker destroys the
Broker client’s state.
To disconnect a Broker Client

name of the client you want to disconnect.
3 On the Client Information page, click the linked value to the right of Sessions.
4 On the Sessions page, click Disconnect One or More Sessions.
5 Select the sessions you want to close, then click Disconnect.
Deleting a Broker Client

When you delete a Broker Client, the Broker client disconnects from the Broker and the
client state is destroyed. You can delete a Broker client regardless of its connection status
or life cycle type.
Important! You cannot undo a client deletion.
To delete a Broker Client and destroy its client state

Clients.
3 On the Clients on Broker page, click Delete Clients on brokername.
4 Select the check box next to each Broker client you want to delete.
5 Click Delete.
The Broker client disconnects from the Broker, and its client state is destroyed.


PART IV
webMethods Broker Administration
Monitoring and Managing Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Territories and Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Managing Broker Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Configuring Administered Objects with the JMS Administrator . . . . . . . . . . . . . . . . . . . . . . 205

CHAPTER 9
Monitoring and Managing Transactions
Using Transaction Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Viewing Running Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Setting the Timeout Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Setting the Recover Mode for XA Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Manually Performing a Commit or Roll Back . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Viewing and Purging Lost Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

CH A P T E R 9 Mo n it o r in g an d M an ag in g Tr an sa ct io n s
Using Transaction Controls

You use the transaction controls in the Broker Administrator to monitor and manage
transactions running under the transaction manager on the Broker. These controls allow
you to monitor the activity of transactions as they execute and take action against
transactions that do not appear to be running correctly.
Transactions that run under the Broker transaction manager include transactions initiated
by regular Broker transactional clients, as well as transactions that are initiated by Broker
JMS Provider.
To access the transaction controls

2 From the Navigation panel, select the Broker with which you want to work.
3 Select the Transactions tab.
Viewing Running Transactions

If a client has started a transaction on the Broker, that transaction will appear on the
Transactions tab. The transaction disappears from this list when the client explicitly ends
the transaction.
In many cases, transactions complete too quickly to be viewed in the transaction list.
However, the list is useful for monitoring the state of long-running transactions and for
spotting transactions that have become hung in the system.
The transaction list provides the following information about a transaction:
Transaction ID. The unique identification number (txid) that the Broker assigns to a
transaction when it starts.
External ID. An identifier that an application can optionally assign to a transaction.
Depending on the application, this value may be empty.
State. The current state of the transaction, which will be one of the following:
Open. The transaction is in progress and has not yet been prepared or committed.
End Success. The transaction has ended with the success flag and not yet been
prepared.
End Failure. The transaction has ended with the failure flag and not yet been
prepared.
Heuristic Commit. The transaction has been heuristically committed.
Heuristic Rollback. The transaction has been heuristically rolled back.

Prepared. The transaction has been prepared, but has not yet been committed or
rolled back.
Committed. The transaction is in the process of being committed.
Rollback. The transaction is being rolled back.
Created. The time at which the transaction was started.
Documents published. The number of documents that the transactional client has
published or delivered within the context of this transaction since the transaction
started. (If the transactional client published other documents during this time under
another transactional context, those documents would be reflected in a separate
transaction entry.)
Documents Ack'ed. The number of documents the transactional client has received and
acknowledged within the context of this specific transaction since the transaction was
started. (If the transactional client received other documents during this time under
another transactional context, those documents would be reflected in a separate
transaction entry.)
Setting the Timeout Options

You can configure the Broker to monitor the length of time between stages of a transaction
and to take a specific action if a transaction exceeds a specified period of time. When a
transaction exceeds the specified time limit (expires), the Broker automatically performs a
commit or roll back for the transaction, depending on the timeout behavior you configure
on the Broker.
Transactions that expire and are completed by the Broker are considered to be heuristically
completed, meaning that the decision to perform a commit or roll back did not come from
the client. As required by the XA Specification, the Broker maintains a record of
heuristically completed transactions in a log.
The Broker allows you to specify separate timeout limits for two stages of a transaction:
The pre-prepare stage. The pre-prepare stage refers to the time interval between the
point at which a transaction begins and the point at which it performs a prepare
operation. If a transactional client does not issue a prepare, a commit, or a roll back
request within the specified timeout period, the Broker automatically performs a roll-
back operation and then terminates the transaction.
The pre-prepare timeout parameter applies to both two-phase transactional clients
and single-phase transactional clients. For two-phase transactions, the pre-prepare
timeout represents the time limit imposed for the period between the start of the
transaction and the receipt of the prepare request. For single-phase transactions, the
timeout setting represents the time limit for the period between the start of the
transaction and the receipt of a commit or roll back request.

You may specify an infinite pre-prepare period (i.e., impose no timeout limit) by
setting the pre-prepare timeout parameter to -1.
The post-prepare stage. In the case of a transaction that uses a two-phase commit, the
post-prepare stage refers to the period from the receipt of the prepare request until
the initiation of the commit or roll back request. In the case of a single-phase commit,
this timeout does not apply. If a transaction exceeds the specified timeout period, the
Broker executes a commit or roll-back operation on behalf of the client and terminates
the transaction. Whether the Broker executes a commit or a roll back depends on the
way in which you configure the Broker’s post-prepare timeout action parameter. The
default is to commit the transaction.
The post-prepare timeout parameter does not apply to single-phase transactions.
You may specify an infinite post-prepare period (i.e., impose no timeout limit) by
setting the post-prepare timeout parameter to -1.
To specify the timeout settings

4 Select Change Transaction Settings.
5 Configure the timeout periods and timeout action, then click Save Changes. The new
timeout setting will apply to transactions that begin after the pre-prepare timeout
parameter has been changed or are prepared after the post-prepare timeout
parameter has been changed.
Setting the Recover Mode for XA Transactions

Change the Recover Mode when working with XA transactions and an application server.
By default, Recover Mode is set to Restricted, which means that a call to the XA Resource’s
recover method resource returns only transactions that were done on behalf of the
Broker client. A setting of Global means that a call to the XA Resource returns all of the
transactions within the Broker.
To specify the timeout settings

4 Select Change Transaction Settings.

5 Select the Recover Mode that you want, then click Save Changes. The new recover mode
setting will apply to XA transactions.
Manually Performing a Commit or Roll Back

You can force a transaction to terminate using the Commit Transactions and Roll Back
commands on the Transactions tab (these commands will not appear on the Transaction tab
unless transactions are running).
You might force a commit or roll back to terminate a transaction instead of waiting for it
to expire. If you have configured the Broker to execute transactions without any imposed
time limits, you will need to use the commit and roll back commands to terminate hung
transactions.
A transaction that you manually commit or roll back is deemed a heuristically completed
transaction (because the decision to commit or roll back was not made by the client) and is
recorded in the lost transaction log.
To Manually Commit or Roll Back a Transaction

4 Select Commit Transactions or Roll Back Transactions, depending on which operation you
want to perform.
5 Select the transactions that you want to commit or roll back and click Commit or Roll
Back.
Viewing and Purging Lost Transactions

When a transaction ends heuristically, that is, when either the Broker or an administrator
makes the decision to perform a commit or roll back for a transaction, that transaction is
written to the Broker’s lost transaction log.
On the Broker, a heuristically completed transaction is referred to as a lost transaction. Lost
transactions are written to the Broker’s lost transaction log, where they remain until they
are explicitly purged by an administrative action.
To purge a transaction from the lost transaction log, you use the Destroy command on the
Lost Transactions screen. When you destroy a transaction, the Broker releases that
transaction’s txid and discards all knowledge it had of the transaction.

To view and purge lost transactions

4 Select Show Lost Transactions to display the list of heuristically completed transactions.
5 If you want to purge transactions, select Destroy Lost Transactions.
6 Select the transactions you want to purge and click Destroy.

CHAPTER 10
Territories and Gateways
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Managing Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Territory Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

C H A P T E R 1 0 Te r r i t o r i e s a n d G a t e w a y s
Overview
This chapter describes territories and territory gateways, and shows you how to use
Broker Administrator to view and control them.
Each territory contains one or more Brokers and is essentially managed as a single entity.
In many ways, a territory acts as a single Broker that spans multiple hosts because all
Brokers in a territory are directly connected to all other Brokers in that territory and share
that configuration. As a result, a client on one Broker can communicate with a client on
another Broker in that same territory even though they are not directly connected to the
same Broker. Territory gateways are used to provide control over documents that pass
from one territory to another, and therefore allow clients to communicate even though
they may not be part of the same administrative domain.
Territories
The Broker-to-Broker feature allows communication among two or more Brokers. This
Broker-to-Broker communication allows applications and adapters to be spread around
your company and still communicate with each other.
When using the Broker-to-Broker feature, Brokers join a territory. All Brokers in a territory
share the same document types and client groups. This shared view of data and semantics
makes communication between client applications possible.
Each Broker communicates directly with every other Broker in its territory, as shown in
the following diagram. This direct connection ensures the fastest communication between
Brokers.
An Example Territory
Client 3
Broker D
Broker B Client 4
Client 1
Broker A
Client 2
Broker C
In the diagram above, the application Client 1 can communicate not only with Client 2 on
the same Broker, but also with Clients 3 and 4 on Broker D.

Territories
Rules Concerning Territories

The following general rules apply to the use of territories.
Brokers
A Broker that is not part of a territory does not have knowledge of any other Brokers.
Brokers within a territory have knowledge only of other Brokers currently in the same
territory.
Once a Broker leaves a territory, it loses knowledge of any Brokers in the territory.
Brokers remaining in the territory lose knowledge of the Broker that has left.
A Broker can be a member of only one territory at a time. To change from one territory
to another, a Broker must leave the first territory and then join the second.
Two or more Brokers on the same host can be members of different territories.
Operations on document types and client groups affect all Brokers in the territory.
Territories
All Brokers in a territory share the same client groups and document types. In effect,
they appear to operate under a single configuration.
Within a territory, documents published on one Broker can be sent to other Brokers
because they are delivered there or because a client on another Broker has a matching
subscription.
You cannot merge territories. To create a single territory where two existed before, the
Brokers in one territory must leave it and then join the second territory.
A territory cannot be empty. To create one, you must find a Broker that does not
belong to any other territory.
Security
Within a territory, either all Brokers use SSL or no Brokers use SSL (i.e., in a territory,
SSL must either be enabled for all Broker Servers or disabled for all Broker Servers).
You cannot mix SSL servers and non-SSL servers in the same territory.
When using SSL, each Broker uses its Broker Server’s SSL configuration for outgoing
connections and for accepting incoming connections.
Clients
Brokers in a territory do not share clients. Although a territory appears to be managed
like a single mega-Broker, each client keeps its queue, and other state information, on
a single Broker.
Because clients are not shared by Brokers, operations on a specific client work only if
the Broker actually hosts the client.

Unique Names
The follow conventions relate to the use of names.
Each Broker on a Broker Server must have a unique name.
Each Broker in a territory must have a name that is unique among Brokers in that
territory.
Territories joined by gateways must all have unique names.
There is no restriction on the uniqueness of names for territories not joined by
gateways. It is possible to have two territories on the same host, both named
“Territory 1.” However, this naming scheme is not recommended. Although having
two territories with the same name on a single host is not a problem for the system, it
can be confusing to users.
Managing Territories
The following sections describe how to create territories and how to make Brokers join
and leave territories. Use Broker Administrator to create, join, and leave territories, and to
display detailed information about a territory.
Creating a Territory
To create a new territory, you must have a Broker that does not belong to any other
territory. You can find Brokers that are not part of a territory by looking at the Brokers
page, as shown below. If a Broker is part of a territory, the name of the territory is listed in
the Territory column.
Brokers Territory column
Territory Column
(this Broker is part of the A Territory)
Note: You should assign static IP addresses and fixed hostnames for any host with a
Broker Server that is used as part of a territory or has gateways.

To create a territory

2 Navigate to the Broker Information page of the Broker for which you will create a
territory. For instructions on opening the Broker Information page, see “Displaying
Broker Statistics” on page 36.
3 Click Create a New Territory.
4 Type the name that is to belong to the territory in the New Territory Name field.
5 Click Create.
The Territory column of the Broker Information page now contains the name of the
new territory.
Viewing Territory Information

You can view detailed information about a territory from the Territories and Territory
Information pages.
To view territory information
1 Open the Broker Administrator if it is not already open

2 Under Network in the navigation menu, click Territories.
The page may take a few moments to load while Broker Administrator scans all
known Broker Servers and Brokers for territories.
The Territories page displays the following information.
Territory Information Description
Name The name of the territory.

Broker A list of Brokers that belong in the territory.
Connected The status of the connection between the current Broker and
the remote Broker.
Connections Status of the connection between the territory Broker and

Recent Deliveries The document traffic on the Broker for the last X minutes.
Where X is the time interval between statistical polls. The
default value is 1 minute. To change the default setting, see
“Viewing and Changing Connection Settings” on page 32.
Gateways Lists the gateways to Brokers in other territories.
3 To learn more about a territory, click on its name in the Territories column.
The Territory Information page displays information that describes the relationships
of the current Broker with other (remote) Brokers in the territory. The Territory
Information page contains the following information.
Name The name of the territory.

Identifying Broker Name of the identifying Broker. This is the first Broker in the
territory.
Authentication Type None. Indicates that SSL is not required for the gateway
connection.
SSL. Indicates that both Servers connected to the gateway use
SSL.
Access Control The entry will be either a yellow warning symbol or a green
check mark.
A green check mark indicates that Access Control is

configured and working.
A yellow warning symbol indicates that ACL is not

accessible and identity settings must be configured.
Encryption Level None

Joining a Territory
You use Broker Administrator to join Brokers to territories, one at a time. For a Broker to
be eligible to join a territory, it must not currently be a member of any other territory. You
should assign static IP addresses and fixed hostnames for any host with a Broker Server
that is used as part of a territory or has gateways.
Note: When creating a territory with Brokers on differing operating systems, you must
take an important step to ensure a reliable connection between the Brokers. When you
create the territory, you should join the Broker with the different operating system first.
Then, you can add all other Brokers to the territory.
For example, if you want to add a Broker from a Windows system to a Solaris Territory,
you would first add the Windows Broker followed by the Solaris Brokers.
To join a territory

2 Navigate to the Broker Information page of the Broker that will join a territory. For
instructions on opening the Broker Information page, see “Displaying Broker
Statistics” on page 36.
If the Broker already belongs to a territory, the Broker Information page will display
the territory information. Before the Broker can join another territory, it must leave
the one to which it currently belongs.
3 Click Join an Existing Territory.
The Join Territories page appears, listing the territories known to Broker
Administrator.
4 Select the identifying Broker in the territory, then click Join.
If the client groups and document type definitions do not match between the Brokers
in the territory, an error message will appear. To join the territory, you can either edit
the document type definitions on the Broker or click Force Join.
If you click Force Join, the Broker will join the territory, synchronizing only the
document type definitions that match. Document type definitions that do not match
are removed from the document type.
Once the Broker has joined the territory, it can communicate with any remote Broker
in the same territory.

Leaving a Territory
To leave a territory

2 Navigate to the Broker Information page of the Broker who will leave a territory. For
instructions on opening the Broker Information page, see “Displaying Broker
Statistics” on page 36.
3 Click Leave Territory.
The Broker is removed from the territory.
Territory Gateways
A territory gateway is a connection between two territories, allowing the transfer of
documents between the territories. One Broker in each territory is designated to
communicate with a companion Broker in the other territory. Each of the two Brokers,
referred to as gateway Brokers, belongs to its own territory, but can share document types
with its companion Broker across the gateway. There can be only one gateway between
any two territories; however, a gateway Broker in one territory can communicate with
gateway Brokers in multiple territories.
Each gateway Broker is configured and maintained independently. By controlling publish
and subscribe permissions and security across the gateway, it is possible to create a
firewall between territories. In this way, it is possible to connect territories having
differing security needs or territories belonging to different companies.
A set of territories connected by gateways forms a graph. The graph cannot have cycles; a
path that traverses the graph should not be able to return to its beginning. Visually, an
acceptable graph looks like a tree. A graph that crosses the boundary between two
administrative domains is shown in the figure below. With the correct permissions set at
each territory gateway, Broker clients 1 and A can communicate with each other.

Territory Gateways
A Territory Graph
A territory
gateway
Territory 2 Territory B
Territory 4
Territory 1 Territory A
Territory C
Territory 3 Client A
Client 1
Firewall between
Territory 5
administrative
domains
To configure a Broker to be a gateway Broker, you must specify the following

information:
Name and location of the remote Broker (on the other side of the gateway)
Note: You should assign static IP addresses and fixed hostnames for any host with a
Broker Server that is used as part of a territory or has gateways.
Security parameters for the gateway (authentication and encryption)
List of shared document types

List of publish and subscribe permissions
Because you configure each side of the gateway independently, the gateway configuration
process takes multiple steps.
Note: Gateway creation will fail if the two territories have incompatible versions of the
webMethods Broker software.
Use the following general steps to configure a gateway. You must perform these steps on
both Brokers participating in the gateway.

To configure a gateway
1 Create the gateway independently on each side of the territory.
To configure a Broker to participate in a gateway, you must provide the name of the
remote territory, the Broker Host and port number of the remote Broker, and the
remote Broker’s name. If any one of these items is incorrect, you cannot create the
gateway. Even after you have configured both Brokers to participate in the gateway, a
connection does not yet exist through the gateway. See “Creating the Gateway (Both
Brokers)” on page 154 or “Creating the Gateway (One Broker)” on page 157 for
detailed instructions.
2 Optionally, configure gateway security.
Set the security parameters on each gateway Broker and check that a secure
connection can be established. For information about setting up SSL support across a
territory gateway, see “Using SSL Across Territory Gateways” on page 180.
Note: It is not necessary to configure the gateway for SSL support before proceeding
on to Step 3. You can perform this step last as long as the owners of both sides of the
gateway perform the steps in the same order.
3 Configure the shared document types.

To be shared, a document type must exist in both territories. Once the document type
has been added to the shared list on both sides of the gateway, webMethods Broker
compares the definition of the document type in each territory. If the document type
definitions are identical, the document type is shared across the gateway.
4 Synchronize changes to the definition of a shared document type in one territory
across the gateway to the territory.
The synchronization of a document type definition spreads to all territory gateways in
a territory graph that share the same document type. In the figure below, changing
the definition of the document type Alpha in Territory 1 causes the definition to
change in all other territories in the graph. As a result, it can be said that Alpha is
shared between Territory 1 and Territory 4. Changing the definition of document type
Gamma in Territory 1 causes the definition to change only in Territory 2 because
Gamma is not shared across the gateway between Territories 2 and 3. As a result,
document type Gamma cannot be shared between Territory 1 and Territory 4.
Sharing Document Types Across Territory Gateways
Shared List Shared List Shared List

Alpha Alpha
Alpha
Beta Beta
Beta
Gamma Gamma
Territory 1 Territory 2 Territory 3 Territory 4

Territory Gateways
5 Configure the document type permissions.

You can limit the flow of documents across territory gateways by controlling
permissions for the documents a Broker can publish across the gateway and the
documents the Broker can subscribe to. You can set permissions only for document
types that are shared across the gateway.
There are two types of permissions:
Remote Broker Can Publish. The Broker will accept documents of this type from the
remote territory.
Remote Broker Can Subscribe. The Broker is allowed to send (publish or deliver)
documents of this type to the remote territory.
In practical terms, Broker Administrator combines Step 3 and Step 5 into a single
interface. In one operation, you select shared document types and assign the publish
and subscribe permissions.
6 Optionally, set up the Gateway keep alive feature. See “Preventing Firewall
Disconnections of Gateways” on page 154.
Using Broker Remote Publish

Remote publish allows a publisher to restrict the distribution of a document. Documents
are published to the clients and gateways of only one remote Broker; therefore,
distribution is limited to other Brokers, depending on the circumstance.
Remote publish is accessed by delivering documents to a special client-id on a remote
Broker. When the remote Broker receives the document, the special client-id triggers the
remote Broker to treat the document as if it had been published by the delivering Broker.
The _env.destId field is removed and the document is enqueued to clients and gateways
with matching subscriptions.
To perform a remote publish, you deliver documents to the client-id:publish on a remote
Broker. For example:
BrokerClient bc;
BrokerEvent event;
[...]
bc.deliver( “/T/OtherBroker/:publish”, event);
If you know that the remote Broker is in the same territory as the delivering Broker, then
you can omit the territory:
bc.deliver( “//OtherBroker/:publish”, event);
If the delivering client is on Broker Q1, which is in the same territory as Broker Q2 and
Broker Q4 and the target remote Broker Q3, then Broker Q2 and Broker Q4 will not

receive the published document. Only the clients of Broker Q3 will receive the published
document. (See the following diagram.)
A Broker Territory
Broker Q1
Broker Q4
Broker Q3
Broker Q2
If the remote Broker is on the other side of a gateway, then the behavior varies slightly, as
summarized in the table below.
Target Remote Broker Document Destination

Broker in same territory All clients on remote Broker
All territories connected via gateways local to the

remote Broker
Broker peer of local All clients on remote Broker
gateway
All Brokers in the remote territory

remote Broker, except the territory of the delivering
Broker
All territories connected via gateways on Brokers in
the remote territory
Broker in different All clients on remote Broker
territory
remote Broker
Same as delivering Same as if the document had been published
Broker

Territory Gateways
Broker Examples
The following examples are based on the Brokers and territories shown in the Broker
Territories diagram. The first letter of the Broker’s name indicates its territory.
Broker Territories
A Territory Gateway
Broker W1
Broker X1
Broker W3 Broker Y1
Broker W2
Broker X2 Broker X3 Broker Z1
Broker in the Same Territory

Example 1: The delivering client is on Broker W1. The target Broker is /W/W2/:publish. A
document is only published to clients of Broker W2.
Example 2: The delivering client is on Broker W1. The target Broker is /W/W3/:publish. A
document is published to clients of Broker W3, which also sends the document to X1,
where it will be distributed as a published document throughout territories X, Y, and Z.
Broker Peer of Local Gateway

The delivering client is on Broker W3. The target Broker is /X/X1/:publish. A document
is published throughout the X, Y, and Z territories. Territory Y has a local gateway on X1,
and territory Z is reached when X3 receives the document.
Broker in a Different Territory

Example 1: The delivering client is on Broker W1. The target Broker is /X/X2/:publish. A
document is only published to clients of Broker X2.
Example 2: The delivering client is on Broker W1. The target Broker is /Y/Y1/:publish. A
document is only published to clients of Broker Y1. A document will never back track
from where it came, so Broker Y1 will not send the document to X1.
Example 3: The delivering client is on Broker W1. Target Broker is /X/X3/:publish. A
document is only published to clients of Broker X3 and to local gateways of X3 (Z1 in this

case). If territory Z had more Brokers and gateways, they would also receive the
document.
Same as Delivering Broker

The delivering client is on Broker W1. The target Broker is /W/W1/:publish. A document
is published to clients of Broker W1, all Brokers of territory W, and all territories
reachable, via gateways. The behavior is identical to publishing the document.
Note: A document using remote publish will look like a delivered document until it
reaches the target Broker. Trace documents and activity traces will record the document
as a delivery. The remote publish trace on the target Broker will also record the
document as a delivery, but the enqueue traces will look like a publish occurred.
Displaying Gateway Information

Use the Gateway Information page to view gateway statistics for a specific territory
gateway.
There are several ways to access the Gateway Information page. The way in which you
access it largely depends on your preference.
Generally, you open the Gateway Information page from the Territories view by
clicking on the name of the gateway.
You can also open the Gateway Information page from the Broker Information page
by clicking the name of the gateway.
You can also access the Gateway information page from the Navigation panel by
following the Territories Broker Gateways path.

Territory Gateways
Gateway Information page
Click here to view and set

the document types
shared between Brokers
The Gateway Information page displays the following information.

Gateway Information Explanation
Brokers are Linked Yes Brokers are connected and able to exchange
documents.
No One or both Brokers are not available.
Status Active The gateway is active.
Paused The gateway has been paused. When a
gateway is paused, it stops all outbound
traffic. The Broker Administrator shows the
name of the session and Broker client that
paused the gateway.

Keep Alive Interval time_interval How often (in seconds) the Broker sends
Keep Alive Events over the Gateway to
prevent the firewall from disconnecting what
it considers to be an idle connection.
If a time interval of 0 has been specified, this
field displays “disabled”. The default is
“disabled.”
Local Documents Waiting Number of documents in queue waiting to be published.
Local Broker: Name Name of the local Broker. Click to open the
Broker Information page.
Description Description of the local gateway Broker.
Connected The status of the connection between the
Broker and the Broker Server.
Territory Name of the territory to which the local
Broker belongs. Click to open the Territory
Information page for this Broker.
Recent Number of documents received by the
Receipts remote Broker. The amount of time between
updates is specified on the Connections page.
Total Receipts Total number of documents received during
lifetime of the Broker.
Last Receipt Date and time of last receipt.
Remote Broker: Name Name and Broker Host of the remote Broker
on the other side of the gateway. Click to
open the Broker Information page.
Description Description of the remote gateway Broker.
The status of the connection between the
Connected Broker and the Broker Server.
Territory Name of the territory to which the remote
Broker belongs. Click to open the Territory
Information page for this Broker.
Recent Number of documents received by the
Receipts remote Broker. The amount of time between
updates is specified on the Connections page.
Total Receipts Total number of documents received during
lifetime of the Broker.

Territory Gateways
Last Receipt Date and time of last receipt.

Shared Number of documents types shared between
Document the Brokers. Click to view the Shared
Types Document Types page.
Authentication Type None Indicates that SSL is not required for the
gateway connection.
SSL Indicates that both Broker Servers connected
to the gateway use SSL.
Access Control The entry will be either a yellow warning
symbol or a green check mark.
A green check mark indicates that Access

Control is configured and working.
A yellow warning symbol indicates that

ACL is not accessible and identity settings
must be configured.
Encryption Level None No encryption specified for this gateway.
U.S. Domestic U.S. domestic grade encryption is enabled for
this gateway.
U.S. Export U.S. export grade encryption is enabled for
this gateway.
Static Forwarding Details... Details regarding static forwarding for this
gateway. Click to view the Static Gateway
Forwarding page and select one of the
following:
Enabled. Static gateway forwarding is
enabled for this gateway.
Disabled. Static gateway forwarding is
disabled for this gateway.
Displaying the Shared Document Type List

Use the Shared Document Types page to view and set the document types shared
between Brokers.
To open the Shared Document Types page, open the Gateway Information page, as
described in the previous section, and click the entry next to Shared Document Types.

The Shared Document Types page displays the Can Subscribe and Can Publish
information for the remote Broker. From this page you configure the document types to
which the remote Broker can subscribe and publish. See “Configuring the Shared
Document Type List (Both Brokers)” on page 155 for instructions.
The Shared Document Types page displays the following information.
Remote Broker Can
Subscribe Statistics Explanation
Document Type Name of the document folder and type.

In Sync yes The document type is shared across the gateway.
no The document type does not exist, is incompatible, or is not
in the shared document type list on the remote side of the
gateway
Filter Displays set filters. For more information about filters, see “Using
Gateway Filters” on page 159.
Remote Broker Can

Publish Statistics Explanation
Document Type Name of the document folder and type.

In Sync yes The document type is shared across the gateway.
no The document type does not exist, is incompatible, or is not
in the shared document type list on the remote side of the
gateway
Pausing or Resuming a Gateway

You can pause activity in a gateway. When the gateway is paused, all outbound
documents are held in the gateway and not propagated. When you resume the Gateway,
the documents are released.
For example, you could pause a gateway, then update document types, territory
configuration, and document permissions, then resume the gateway. This ensures that all
changes are propagated at once.
To pause or resume activity on a Gateway

2 Navigate to the Gateway Information page. See “Displaying Gateway Information”
above for instructions.

Territory Gateways
3 Click Pause Gateway to pause activity on the Gateway or Resume Gateway to resume
activity on the Gateway.
Static Gateway Forwarding

The static gateway forwarding feature ensures consistent document flow across a gateway
between two territories at all times. Documents defined by the gateway permissions list
are allowed to flow over the gateway. Once static gateway forwarding is enabled, the
documents are forwarded to the remote territory at all times, regardless of any client
subscriptions on the remote territory.
Essentially, the static gateway forwarding feature force feeds documents to the remote
territory. When there are no subscribers on the remote territory, forwarded documents
will be dropped at the gateway peer of the remote territory. Disabling static gateway
forwarding resumes the normal behavior of subscription based gateway forwarding.
Note: The static gateway forwarding feature is only supported on a webMethods Broker
6.5 (or Version 6.1 Service Pack 4 and later). This means that the gateway Broker on which
the static forwarding option is applied to must be a Version 6.5 of Broker. The Broker(s) on
the other end of the gateway can be of any version.
In addition, you cannot enable static gateway forwarding on a Broker that is either not in
a territory or does not have a gateway to the specified remote territory.
To enable static gateway forwarding

3 Look for Static Forwarding and click Details.... The Static Gateway Forwarding dialog box
appears indicating that static forwarding is disabled.
4 To enable static forwarding, select Enable and then click Set Static Forwarding.
5 To check that static forwarding is enabled, click Details... again and verify on the Static
Gateway Forwarding dialog box.
To disable static gateway forwarding

3 Look for Static Forwarding and click Details.... The Static Gateway Forwarding dialog box
appears indicating if static forwarding is enabled.

4 To disable static forwarding, select Disable and then click Set Static Forwarding.
5 To check that static forwarding is disabled, click Details... again and verify on the Static
Gateway Forwarding dialog box.
Preventing Firewall Disconnections of Gateways

You can ensure that a territory Gateway remains connected by configuring the Broker
Administrator to send “keep alive events” over the Gateway. You can control how often
the Broker Administrator sends the keep alive events.
Note: Small values, such as 1 or 2 seconds, will generate excessive network traffic. Check
your firewall configuration to find a reasonable value for this interval.
Specifying a gateway keep alive interval

above for instructions.
3 Click Change Keep Alive Interval.
4 In the Keep Alive Interval field, specify how many seconds the Broker should wait
between sending keep alive events over the Gateway.
Configuring a Gateway if You Control Both Brokers

It is easiest to configure a territory gateway if you control both sides of the gateway
because Broker Administrator can do much of the work for you. There are two major
steps in configuring the gateway:
1 Create the gateway.
2 Configure the shared document type list.
Creating the Gateway (Both Brokers)
To create a territory gateway when you control both Brokers

2 Make sure the Broker Administrator is connected to both sides of the territory
gateway.

Territory Gateways
You can confirm the connection by making sure that both of the Brokers you have
chosen to participate in the gateway are visible from the Broker Administrator. There
are a number of ways to do this.
One approach is to use just the Navigation panel. Adjust the display so that you
see the Broker Servers and all the Brokers under them. If the two gateway Brokers
are shown, then they are connected to the Broker Administrator.
An alternative approach is to navigate to the Broker Server page for each Broker
Server and make sure the gateway Broker is displayed there. See “Adding a
Broker Server to Broker Administrator” on page 45 for instructions.
3 Open the Territory Information page of one of the territory Brokers. See “Viewing
Territory Information” on page 139 for instructions.
4 In the Territories list, select the Broker you have chosen to be the local gateway Broker.
5 Click Create a Territory Gateway.
6 Under Local Territory on the Create a Territory Gateway page, select Create both Sides of
Gateway.
7 In the Remote Territory box, select the name of the remote territory and the remote
gateway Broker.
8 Click Create.
Both sides of the gateway are created. Now you can configure the document types to
which the remote Broker can subscribe and publish. See “Configuring the Shared
Document Type List (Both Brokers)” below for instructions for sharing document
types between Brokers.
Configuring the Shared Document Type List (Both Brokers)

Once you have created both sides of the territory gateway, you can edit the shared
document type list. There are two ways to edit this list: by individual document types or
by client groups. In either case, you must first display the Gateway Information page for
either of the gateway Brokers.
Editing by Document Type
To edit the shared Document Type list by individual document type
1 Determine the permission to be assigned to each document type.

Permissions are based on what you will allow the remote Broker to do; the remote
Broker can publish or can subscribe (or both).
2 Open the Shared Document Types page. For instructions on opening the Shared
document types page, see “Displaying the Shared Document Type List” on page 151.
3 Click Add Can Subscribe Types or Add Can Publish Types.

4 In the Add Document Types table, select one or more document types and click Add.
You are given the option of setting up shared document types permissions on the
other side of the gateway or updating only the current side.
5 Click Yes or No, then click Update to synchronize the document types.
Broker Administrator synchronizes the Shared Document Type list on the two gateway
Brokers, as shown in the next figure. For example, for each document type listed in
the Remote Broker Can Subscribe panel for Broker A, Broker Administrator places
that document type in the Remote Broker Can Publish panel of Broker B.
If there is no matching document type on the remote Broker, or if the document types
are not identical, Broker Administrator cannot synchronize the shared document
type.
Synchronizing Shared Document Types
Broker A Territory 1 Broker B Territory 2
Because Broker Administrator has performed some of the configuration

automatically, you should examine the permissions lists for both gateway Brokers in
case you want to adjust the selection. Once you have synchronized the shared
document types for both Can Publish and Can Subscribe permissions, the territory
gateway is ready for traffic.
Editing by Client Group

You may want to set permissions for an entire client group at once. In this case, Broker
Administrator assumes that all permissions for both sides of the gateway should mirror
each other.
To edit the shared Document Type list by client group
2 Click Hook Up Client Groups.
3 Select one or more client groups and click Add.
4 You have the option of setting up shared document types permissions on the other
side of the gateway or updating only the current side.

Territory Gateways
Click Yes or No, then click Update to synchronize the document types.
Broker Administrator populates the shared document type list of both Brokers,
assigns Can Publish and Can Subscribe permission to all document types, and then
synchronizes the document types across the gateway.
Because Broker Administrator has performed some of the configuration
automatically, you should examine the permissions lists for both gateway Brokers in
case you want to adjust the selection. Once you have synchronized the shared
document types for both Can Publish and Can Subscribe permissions, the territory
gateway is ready for traffic.
Configuring a Gateway If You Control One Broker

When you configure a gateway that crosses administrative domains (such as between two
companies), it is likely that you will have control over only one of the gateway Brokers. In
such a case, you need to perform the configuration in collaboration with the owner of the
remote Broker. There are two major steps in configuring the gateway:
1 Create the gateway.
2 Configure the shared document type list.
Creating the Gateway (One Broker)
To create a territory gateway when you control only one Broker

2 Open the Territory Information page of the territory Broker. See “Viewing Territory
Information” on page 139 for instructions.
3 In the Territories list, select the Broker on which you will create the gateway.
4 Click Create a Territory Gateway.
5 Under Local Territory, select Create one side of the Gateway.
6 Enter the name of the remote territory, host, port and Broker in the appropriate fields.
7 Click Create.
One side of the gateway is created. Both sides of the gateway MUST be created in order
to configure the document types to which the remote Broker can subscribe and
publish.

Configuring the Shared Document Type List (One Broker)

To configure the shared document type list, both sides of the gateway must be configured.
Configure the other side of the gateway, then follow the instructions in “Configuring the
Shared Document Type List (Both Brokers)” on page 155 to set up the Shared Document
Types list.
Removing a Shared Document Type

You can remove one or more document types from the shared document type list of a
territory gateway. If you do not control the remote gateway Broker, you should
coordinate the removal of document types with the owner of the remote Broker.
To remove a document type from the list

2 Open the Gateway Information page of the territory Broker. See “Displaying Gateway
Information” on page 148 for instructions.
3 Click Delete Shared Document Types.
4 In the Delete Document Types table, select one or more document types and click Delete.
You are given the option of setting up shared document types permissions on the
other side of the gateway or updating only the current side.
5 Click Yes or No, then click Update to synchronize the document types.
Removing a Territory Gateway

Because both sides of a territory gateway are created independently, you can also remove
each side independently. If you only remove one side, however, the effect is the same
because both sides are needed to maintain a connection. If you do not control the remote
gateway Broker, you should coordinate the removal of the gateway with the owner of the
remote Broker.
Important! If you control only one side of a territory gateway and find it necessary to
remove the gateway, there is no simple method to restore the connection. To restore the
gateway, you need to recreate the Can Subscribe and Can Publish lists for the remote
Broker.
To remove a territory gateway

2 Open the Gateway Information page of the Gateway Broker. See “Displaying
Gateway Information” on page 148 for instructions.

Territory Gateways
3 Click Remove Gateway.

4 Select either Remove Both Sides of Gateway or Remove One Side of Gateway.
5 Click Remove.
Using Gateway Filters

A filter string specifies criteria for the contents of a document. The Broker uses the filter
string to determine which documents match your criteria. The Broker allows only those
documents that match the filter string to pass through the gateway to the remote Broker.
For information about the syntax of filter strings, see “Filtering Documents” on page 159.
To place a gateway filter on a document type

3 In the Remote Can Subscribe table, click Edit Filter next to the document type to which
you will add a filter.
4 Enter the filter string in the Edit Adapter::Document type field. Document type represents
the name of the document type to which you are adding the filter. Filter syntax and
filter rules are described in the next sections.
5 Click Submit Changes.
The gateway filter appears in the Filter column of the Remote Can Subscribe table.
Filtering Documents
As mentioned above, a filter string specifies criteria for the contents of a document. For
example, assume that a document contains a person’s age and state of residence. The first
document field has the name age and the second has the field name state. The following
filter string matches only those documents whose age field is greater than 65 and whose
state field is equal to FL.
age > 65 and state = "FL"
In this example filter string, age and state represent document fields. This filter also
contains an arithmetic constant 65 and a string constant "FL". The boolean operator and
combines the field criterion for age and state.
Other example filter specifications are as follows:
debt > salary*0.50
packaging = "portable" and price > 5000
answer = ’Y’ or answer = ’y’
(answer = ’Y’) or (answer = ’Y’)

Filter strings can do any combination of the following:

Compare document field contents against constants or computed values.
Combine document field comparisons using the boolean operators and, or and not.
Perform arithmetic operations on document fields and constants.

Contain regular expressions.
Contain string and arithmetic constants.
Contain a hint that specifies how documents should be processed.

For information about using regular expressions, hints, and filter functions from the
webMethods Broker library, see the appropriate programmer’s reference manual.
Filter Rules
Filter strings must adhere to the following rules:
Field names can be fully qualified, such as:
struct_field.seq_field[2]
A character constant is a single character surrounded by single quotation marks. For

example:
’A’
A string constant is zero or more characters surrounded by double quotation marks.

For example:
"account"
If a character or string constant contains a single or double quotation mark, precede

the quote with a backslash. For example:
‘\"’
You can use parentheses to control the order of operator precedence.
Filter Operators
The following tables contain the various operators that you can use to create filters. For a
more complete list of operators, see the appropriate programmer’s reference manual.
Note: The Integration Server and Developer use different filter syntax for subscribing to
publishable documents. See webMethods Developer User’s Guide for more information.
Type of Operator Operator Description
Logical Filter Operators !

Not
not

Territory Gateways
&&
And
and
||
Or
or
Note: Logical filter operator expressions are evaluated in a method similar to SQL
expression evaluation, in that all operators are always evaluated. When a logical filter
operator expression contains multiple operators, operator precedence determines the
sequence in which the operations are performed. For example, when evaluating the
expression “A OR B”, both “A” and “B” are evaluated, even if “A” evaluates to a true
value.
Comparison Filter Operators < Less than

<= Less than or equal to
> Greater than
>= Greater than or equal to
= Equal to
== Equal to
!= Not equal to
Arithmetic Filter Operators - Unary minus
* Multiplication
/ Division
% Modulus Division
- Subtraction
+ Addition
Note: Implicit type conversion occurs when operands in an arithmetic operation have
different types. The operands are converted to a larger value before the comparison
occurs. Type char is considered numeric, but boolean is not.
String Operators + Concatenation

< Less than
<= Less than or equal to
> Greater than
>= Greater than or equal to
= Equal to

== Equal to
!= Not equal to

CHAPTER 11
Managing Broker Security
Security Using Secure Sockets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Using webMethods Broker with SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Using SSL for Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Using SSL Across Territory Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Creating and Managing SSL Certificate Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Working with Firewalls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Using Access Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

C H A P T E R 11 M a n a g i n g B r o k e r S e c u r i t y
Security Using Secure Sockets

For a description of Secure Sockets Layer (SSL), public key encryption, and the
certificate files that support encryption, see “A Brief Description of SSL” below.
For information about how to create and manage SSL certificate files, see “Creating
and Managing SSL Certificate Files” on page 183.
For information about how to set up the Broker Server to use SSL, see “Configuring
the webMethods Broker Server for SSL” on page 171.
For information about content-based security using access labels, see “Using Access
Labels” on page 195.
A Brief Description of SSL

Secure sockets are a means of making communications over a network safe. Using secure
sockets, you can have encrypt data so that people with access to the network cannot read
it. It is also possible to identify the sender of the data so other people cannot pretend to be
you or pretend to be the Broker Server you are accessing. This identification process is
called authentication.
One standard for secure sockets is called the Secure Sockets Layer (SSL) standard. SSL
supports data encryption, Broker Server authentication, and client authentication.
webMethods Broker complies with the SSL 3.0 specification and the TLS 1.0 specification.
Public Key Encryption

Encryption is the process of changing data into a form that makes it unreadable, especially
for those whom it is not intended. Encryption algorithms require the use of some secret
information called a key. Public key encryption uses a pair of keys: a public key and a
private key. You can give out the public key, but you keep the private key to yourself.
Anyone with the public key can encrypt a message, but only someone with the private
key can decrypt it.
The SSL support in webMethods Broker uses certain RSA encryption algorithms. RSA has
defined a public-key cryptosystem for both encryption and authentication.
Note: webMethods Broker is not compatible with products that use the DSA encryption
algorithms for SSL, such as Java version 1.1 from Sun Microsystems, Inc.
The public key is part of a certificate, which is a digital document verifying that a public
key belongs to a given entity. In addition to the public key, the certificate contains a
distinguished name and information about the issuer of the certificate. A keystore is a file
that contains private keys and public certificates. The webMethods Broker keystore file
format is proprietary and password-protected. Certificates are issued by a Certification
Authority, a trusted central organization that attests to the identities of those to whom it
issues the certificates.

Security Using Secure Sockets
The choice of a Certification Authority depends on the needs of your organization. You
can subscribe to digital certificate services or you can create a Certification Authority
within your own organization using third-party software products.
Modes of Secure Sockets

SSL allows for a number of ways to make connections. There are two key features that can
be controlled: who has to provide certificates, and whether or not the data is encrypted.
If you are using SSL, the Broker Server must always provide a certificate. The client
software has the option of whether or not to provide a certificate. When the client
provides a certificate, the communication is slightly more secure, and the Broker Server is
told the client's identity. In both cases, the client is told the Broker Server’s identity.
Use of the Access Control List feature, described in “Access Control Lists” on page 167,
requires the client to provide a certificate.
You can choose whether or not the data is encrypted. When communication is not
encrypted, secure sockets still provide two benefits:
The identity of the client is passed to the Broker Server for verification
The data is known to be undamaged upon arrival.

This option can be useful when your network is trusted but you want users to be
identified to the Broker Server.
webMethods Broker supports the following options for SSL:
Do not use SSL (this is the default).
Use SSL; only the Broker Server has a certificate (provides Broker Server
authentication and optional encryption).
Use SSL; both the Broker Server and the client application have certificates (provides
Broker Server and client authentication, and optional encryption).
The client application determines whether or not communication is encrypted. Also,
the Broker’s client groups can require the use of encryption.
Trusted Roots
Certificates issued by a Certification Authority are usually associated with an
Authentication Server. It is possible to check whether any issued certificate is valid by
contacting the appropriate Authentication Server. Unless you run your own
Authentication Server, this form of authentication requires a constant Internet connection.
To remove the need for an Authentication Server, webMethods Broker uses a concept
known as a trusted root. A trusted root is a special certificate belonging to a Certification
Authority. This special certificate contains the Certification Authority's public key, and
must be well-known and trusted. Your other certificates are themselves encrypted using
the Certification Authority's private key in such a way that the certificates can be

validated. There is one trusted root for each Certification Authority that issues certificates.
The validation is done using the special trusted root certificate. A given company may
have multiple Certification Authorities, each with a different trusted root.
For the client to authenticate the Broker Server, the client needs access to the keystore
containing the Broker Server certificates’ trusted root so the client can validate the Broker
Server’s certificate.
Note: A keystore is a file that contains private keys and public certificates. The webMethods
Broker keystore file format is proprietary and password-protected.
For the Broker Server to authenticate the client, the Broker Server needs access to a
certificate file that contains the client certificates’ trusted root so that the Broker Server can
validate the client’s certificate.
Distinguished Names
A distinguished name is that portion of a certificate that identifies either the owner of the
certificate or the issuer of the certificate. If the distinguished name identifies the issuer, it
is a trusted root, described in above in “Trusted Roots”. The table below shows the fields
that make up a distinguished name.
Tag Field
CN Common Name
OU Organizational Unit
O Organization
L Locality
ST State or Province
C Country
EM E-mail Address
webMethods Broker accepts distinguished names in the following format:

A field consists of a tag and a value, separated by an equal sign.
Fields are separated by commas.

Tags are not case sensitive (CN or cn).
Order of the fields is not important.
If a field is not set, it is omitted.

Values must be quoted if they contain commas or equal signs.

Using webMethods Broker with SSL
Here is an example of a distinguished name:

CN=John Smith,OU=Engineering,O=webMethods,
L=Sunnyvale,ST=CA,C=USA,EM=jsmith@webMethods.com
webMethods Broker supports the use of multi-valued attributes, separated by commas,

within distinguished names. For example, a distinguished name could have two common
names, such as:
CN=John Smith,CN=JSMITH
In the Broker Administrator, if you use multi-valued attributes in distinguished names

and type them manually (as opposed to selecting them in a dialog box), you must enter
the text of all attributes exactly as it appears in the certificate file. Otherwise, the
distinguished name will not appear to match the certificate file.
The command awcert, used to manage certificate files, has some additional conventions
for using distinguished names, as described in “Using Distinguished Names with awcert”
on page 193.

To provide SSL support in webMethods Broker, you must enable SSL for the Broker
Server and for each client application, adapter, or webMethods Broker tool.
When an individual client establishes a connection with the Broker Server, the client sets
the mode of operation for the connection:
Broker Server authentication only
Client and Broker Server authentication
Encryption is enabled or disabled

When using SSL, Broker Administrator can optionally use client and server authentication
for connections with the Broker Server.
Access Control Lists

The Broker Administrator allows you to set up Access Control Lists (ACLs). With ACLs you
can control access to Broker Servers, to the Brokers on those Broker Servers, and to client
groups. To gain access, a client must have an identity (distinguished name and
authenticator’s distinguished name) that matches the ACL.
You can administer Broker Servers (and Brokers, Clients, Client groups, etc.) by using the
Broker Administrator (which runs as a package on the Integration Server) or through a
client that is running the Broker administrative API.

Note: The administrative API is a set of Java services that you can use to administer Broker
objects. You can write your own user interface that uses the services, or you can use the
services without a user interface and make administrative changes programmatically.
You can limit the administrative tasks a user is allowed to perform against these objects by
using ACLs.
Note: It is possible for Broker Administrator application to not have administrative access
to a Broker Server, but still have access to a Broker that resides on that Broker Server. This
is called “Limited Access.” If administrative access is limited, “Limited Access” appears in
the title bar of the Broker Server Information page.
Note: If you want to secure your Broker system using SSL and ACL, you should also
secure the system-defined eventLog client group either by restricting access to it through
an ACL or removing the eventLog client group when sensitive information is passed
through the Broker. The eventLog client group is used by custom developed document
logging utilities, and as such, the eventLog client group is permitted to subscribe to all
document types defined within the Broker.
If there are no customized document logging utilities that require the eventLog client
group, then delete the eventLog client group. For more information, see “Deleting a
Client Group” on page 104.
If there are customized document logging utilities that require the eventLog client
deployed in the Broker, secure the eventLog client group with an ACL. For more
information, see “Setting Up Client Group Access Control Lists” on page 177.
Administrative Access to webMethods Broker Servers

The following list shows administrative tasks that all clients can perform versus the tasks
that only clients with ACL access can perform. Clients include an Integration Server
running the Broker Administrator package, an Integration Server running the Broker
administrative API, and non-Integration Server clients running the Broker administrative
API.
Only clients with ACL access on the Broker Server

Any client can perform these tasks: can perform these tasks:
See the names of Brokers and Create new Brokers

which one is the default Broker
Administer individual Brokers Get or set the SSL configuration
(provided the client is on the ACL
for the Broker)

See usage statistics Get or set the Broker Server’s ACL

configuration
See the logging configuration Purge log entries
Find out whether SSL is Stop the Broker process (for all Brokers on
configured (but not see the Broker a Broker Server)
Server’s SSL identity)
See the Broker Server description Get or set the license key
Set the logging configuration
Set the host description
You will need to be prepared to provide a list of distinguished names that should have
administrative access to the Broker Server. For information, see “Setting Up Access
Control Lists for the webMethods Broker Server” on page 176.
Note: The ACL must include a distinguished name that you currently use so that you can
have continued administrative access to the Broker Server.
Administrative Access to Client Groups

It is possible to limit the administrative tasks that a client can perform against a client
group. You can limit the access to clients that present a specific distinguished name.
To limit access to a client group, modify the contents of the Access Control page of the
appropriate Client Group Information page. You will need to provide a list of
distinguished names that should have access to the client group. For a step-by-step
description of modifying ACLs for client groups, see “Setting Up Client Group Access
Control Lists” on page 177.
Client Access to Broker Server

When a non-volatile client is created on an authenticated connection, the new client
inherits the authenticated identity (distinguished name and authenticator’s distinguished
name) from the connection. The client must present the same identity each time it
reconnects to the Broker Server.
Note: Volatile clients cannot reconnect since they have a Destroy on Disconnect life cycle.
Administrative Access to Brokers

It is possible to limit administrative access to a specified Broker. Without administrative
access, the only activity that can be performed is to see the Broker’s name and description.
You are denied access to client groups, clients, and document types, and to the Broker
Information page.

If the Broker Administrator does not have administrative access to a Broker, the Broker
Information page displays “Access Denied” in the Territory field, as shown below.
Administrative Access to a Broker
Broker is locked
As shown above, it is possible for Broker Administrator to have administrative access to a

Broker Server and not have access to a Broker that resides on it.
Limiting access to a Broker is a specific instance of limiting access to client groups. To
limit access to a Broker, modify the contents of the Broker’s client group Access Control
page.
You will need to provide a list of distinguished names that should have administrative
access to the Broker. For a step-by-step description of modifying ACLs for client groups,
see “Setting Up Client Group Access Control Lists” on page 177.
A Roadmap for Implementing SSL Support
To implement SSL support in webMethods Broker
1 Create the certificate file(s) needed by the Broker Server and each client.
The Broker Server and each client must have access to the certificates needed to
authenticate the connection. Certificates reside in keystores certificate files on the
Broker Server and on hosts where client applications and adapters reside. The
contents of each certificate file depends on the host it is located on and the type of
authentication, as shown below.
Broker Server Host certificate

Type of Authentication Client host certificate file file
Broker Server Broker Server trusted root Broker Server private key,
authentication only certificate, and trusted root
Client and Broker Broker Server trusted root; Broker Server private key,
Server client private key, certificate, certificate, and trusted root;
authentication and trusted root client trusted root

You must place the distinguished name of the issuer of the Broker Server’s certificate
in the certificate file on each client host. If you need client authentication, you also
need to place the distinguished name of the issuer of a certificate belonging to a client
in the certificate file on the Broker Server Host.
For information about how to manage client and Broker Server private keys,
certificates and certificate files, see “Creating and Managing SSL Certificate Files” on
page 183.
2 Configure the Broker Server to enable SSL. This procedure is described in “Enabling
SSL for the webMethods Broker Server” on page 175.
3 Configure each client to enable SSL.
You can find information about how to configure clients for SSL support in the
following locations:
For this client... Look in...
Adapters In the appropriate adapter documentation, the section on

configuring the adapter
Client applications The appropriate programming interface manual
Integration Server webMethods Integration Server Administrator’s Guide
Broker “Configuring Broker Administrator for SSL Support” on
Administrator page 173
Configuring the webMethods Broker Server for SSL
To configure the webMethods Broker Server for use with SSL
1 Make sure the Broker Server has the SSL license key.
See “Determining If You Have an SSL License Key” on page 172.
2 Make sure that the proper certificate files are available on the Broker Server Host.
See “Preparing the Certificate File for the Broker Server” on page 172.
3 If required, enable SSL for the Broker Administrator so that it can have administrative
access to the Broker Server or to a specific Broker.
You must enable SSL for the Broker Administrator before you can create the ACL for
the Broker Server in the next step. See “Configuring Broker Administrator for SSL
Support” on page 173.
4 Using the Broker Administrator, enable SSL for the Broker Server.
See “Enabling SSL for the webMethods Broker Server” on page 175.

5 If required, set up an ACL to control administrative access to the Broker Server.

See “Setting Up Access Control Lists for the webMethods Broker Server” on page 176.
6 If required, set up ACLs to control administrative access to Brokers.
See “Setting Up Client Group Access Control Lists” on page 177.
Determining If You Have an SSL License Key

To configure the Broker Server to support SSL, you must first have a run-time license key
for your Broker Server that enables secure sockets. You can use the Broker Administrator
to determine if your Broker Server is licensed to support secure sockets.
To determine if your Broker Server is licensed to support secure sockets

2 Navigate to the Broker Server Information page. For instructions on opening this
page, see “Displaying webMethods Broker Server Properties” on page 34.
3 Check the SSL entry. The entry will be either a yellow warning symbol or a green
check mark.
A green check mark indicates that SSL is configured and working.
A yellow warning symbol indicates that SSL needs to be configured.
4 If SSL is configured, you can modify the configuration on the current Broker Server by
clicking the entry or you can proceed to “Setting Up Access Control Lists for the
webMethods Broker Server” on page 176.
If SSL is not configured, you can configure SSL by clicking the entry and following the
instructions outlined in “Configuring Broker Administrator for SSL Support” on
page 173.
Preparing the Certificate File for the Broker Server

To enable SSL on the Broker Server, first create a certificate file and put the certificate file
in an accessible location on the Broker Server Host.
The certificate file must contain at least one certificate for the Broker Server and the
distinguished name for the issuer of that certificate, as well as the distinguished names for
any issuers of client certificates. See “Creating and Managing SSL Certificate Files” on
page 183 for the actual steps for preparing a certificate file.

Configuring Broker Administrator for SSL Support

If a Broker or a Broker Server has ACL access control enabled, Broker Administrator
cannot have administrative access to it unless it is configured for SSL and has a certificate
containing a distinguished name that is on the Broker’s or Broker Server’s ACL. The
content of the certificate file used by Broker Administrator is described in the table on
page 170.
Note: SSL must be enabled for the Broker Administrator before you can use it to create an
ACL for the Broker Server.
Securing Broker Administrator (Defining an Identity for Broker Administrator)

For full end-to-end SSL protection you will need a total of two secure connections and two
sets of certificates:
1 From Broker Administrator to the Broker Server being managed
2 From the client to Broker Administrator itself
Accordingly, two sets of certificates will be required: One certificate will certify
communications between any HTTP client (SSL client) and Broker Administrator (SSL
Server). The other will certify the connection between Broker Administrator (SSL client)
and the Broker Server(s) (SSL Server) to which they are connected.
To configure the Broker Administrator for SSL support

2 From the Navigation panel, under Settings, click Identity.
3 On the Identity page, click Change Identity Settings.
4 If a certificate file has already been defined to the Broker Administrator, select the one
you want to use from the list provided and click Proceed to Next Step, then go to step 5,
below.

If a certificate file has not already been defined to the Broker Administrator, click Add
Certificate.
a In the Certificate File field, enter the location of the certificate file. If you want to
assign a different name to this certificate, enter an optional name (.cert suffix will
be added automatically) in the Certificate Name field and click Proceed to Next Step.
Note: In Broker Administrator, when configuring SSL on a Broker Server that installed on
“
a different host than the host that is running Broker Administrator, the path to the
certificate file must be resolvable on both the Broker Server host and the Broker
Administrator host.
For example, if your Broker Server host is installed on Solaris and your Broker
Administrator server is on Windows, if you specify that the certificate path on your
Broker Server is “/temp/devtest6d.cert”, then your Broker Administrator host needs to
have the same certificate in its c:\tmp directory. If the path is not resolvable on both hosts,
then you would receive the following error for this example:
Error: the following Exception was thrown: Secure socket certificate file
“c:\tmp\devtest6d.cert' was not found on the Broker host.”
b Navigate back to the Identities page (either through the Navigation panel or the
Identities tab).
c Click Change Identity Settings.
d Select the certificate you want to use and click Proceed to Next Step.
5 On the SSL Password page, type the certificate file password and then click Proceed to
Next Step.
6 On the Identity User Name page, select one of the distinguished user names provided
by the certificate. This distinguished name will be the identity the Broker
Administrator uses when it connects to the Broker Servers and Brokers that it
administers.
7 Click Finished.
The Broker Administrator updates the identity settings and starts new connections
with each Broker Server. This process can take a few minutes, depending on the
number of known Broker Servers.
Note: If other Broker Administrator pages are open, they may need to be refreshed in order
to display the new identity settings.

Note: If you want to secure your Broker system, you should either: 1) secure the system-
defined eventLog client group with an ACL or 2) delete the eventLog client group when
sensitive information is passed through the Broker. The eventLog client group is used by
customized document logging utilities, and as such, the eventLog client group is
permitted to subscribe to all document types defined within the Broker.
If there are no customized document logging utilities that require the eventLog client
group, then delete the eventLog client group. For more information, see “Deleting a
Client Group” on page 104.
deployed in the Broker, secure the eventLog client group with an ACL. For more
information, see “Setting Up Client Group Access Control Lists” on page 177.
Enabling SSL for the webMethods Broker Server

Once the certificate file is in place on the Broker Server Host and the Broker Administrator
has been configured for SSL support, you can set up the Broker Server to use SSL.
To set up the Broker Server to use SSL
1 Check the Identity Settings for the Broker Administrator to make sure that an
administrative identity has already been established. If not, you will need to establish
an identity for the Broker Administrator. See “Configuring Broker Administrator for
SSL Support” on page 173 for instructions.
2 Once the Identity Settings are established on the Broker Administrator, open the
Broker Server Information page for the Broker Server.
3 From the Broker Server Information page, click the linked value to the right of SSL.
4 Click Change Configuration on Restart to add a certificate file.
5 When the SSL Certificate File - Step 1 of 2 page appears, enter the location of the
certificate file in the Certificate Path field, then click Proceed to Next Step.
6 Enter the password for the certificate file, then click Save Changes.
7 When the Distinguished User Name - Step 2 of 2 page appears, select one of the
distinguished user names provided by the certificate.
8 Click Finished.
Broker Administrator updates the SSL settings and starts a new connection with the
Broker Server.
9 Optionally, to further limit the administrative access on the Broker Server, create and
configure ACLs for the Broker Server. See “Setting Up Access Control Lists for the
webMethods Broker Server” on page 176 for instructions.

Setting Up Access Control Lists for the webMethods Broker Server

Once SSL is enabled for the Broker Server, you can set up an ACL to limit administrative
access to the Broker Server. Administrative tasks affected by this action are listed in
“Administrative Access to webMethods Broker Servers” on page 168. You can use the
Broker Administrator to set up a Broker Server ACL.
Note: Before you can establish an ACL for a Broker Server, you must configure the Broker
Administrator with an identity that matches the Broker Server ACL. See “Configuring
Broker Administrator for SSL Support” on page 173.
To set up a Broker Server ACL

2 Navigate to the Broker Server Information page. For instructions on opening this
page, see “Displaying webMethods Broker Server Properties” on page 34.
3 Click the linked value to the right of the Access Control field.
4 Click Enable Authentication (administrative clients must connect using SSL).
The Access Control page appears, displaying the Authenticator Names that are
specified in Broker Server’s certificate file.
5 Edit the list of Authenticator Names so that it contains only the distinguished names
of issuers allowed to provide authentication.
To remove an issuer, click Delete Authenticator Names. On the Delete Authenticator
Name page, select the issuer that you want to delete, then click Delete.
To add an issuer, click Add Authenticator Names. On the Add Authenticator Name
page, select the issuer that you want to add, then click Add.
Note: If you cannot find the distinguished name of a particular issuer, you must
add it to the certificate file. See “Creating and Managing SSL Certificate Files” on
page 183.
6 Optionally, click Add User Names to specify which individual clients can have access.
Note: If you do not specify which individual clients can have access, any user with a
distinguished name from an issuer in the Authenticator Name list can have
administrative access to the Broker Server.
Either enter the User Name into the User Name field or select one of the User Names in
the User Name list.
7 Click Add.

Note: For every client distinguished name that appears in the user name list of the
Access Control tab, the distinguished name of the certificate’s issuer must appear in
the authenticator name list. If not, you must add it to the certificate file used by the
Broker Server. See “Creating and Managing SSL Certificate Files” on page 183.
Setting Up Client Group Access Control Lists

Once SSL is enabled, you can set up client groups so that only certain clients can connect
using a specific client group. Clients are identified by the distinguished name. You can
also limit access to a client group based upon the issuer of the client's certificate. For
example, you could allow access only from clients with valid certificates from your
company's Certification Authority.
A specific instance of using client group ACLs is to limit administrative access to a specific
Broker. To limit access, establish an ACL for the admin client group associated with that
Broker.
deployed in the Broker, secure the eventLog client group with an ACL.
To set up Client Group access control lists

2 From the Navigation panel, navigate to the client group for which you want to
establish an ACL.
3 View Access Control status on the Client Group Information table.
4 If the status is Disabled, click it to enable Access Control.
If the status is Not accessible, SSL required, then SSL is not configured. You must
configure SSL before you can set up the ACL. See “Enabling SSL for the webMethods
Broker Server” on page 175 for instructions.
If the status is Not accessible, Identity required, then SSL is configured, but you are not
identified to the Broker Server. You must configure the Broker Administrator identity
settings before you can set up the ACL. See “Configuring Broker Administrator for
6 Edit the list of Authenticator Names so that it contains only the distinguished names
of issuers allowed to provide authentication.
To remove an issuer, click Delete Authenticator Names. On the Delete Authenticator
Name page, select the issuer that you want to delete, then click Delete.

To add an issuer, click Add Authenticator Names. On the Add Authenticator Name
page, select the issuer that you want to add, then click Add.
Note: If you cannot find the distinguished name of a particular issuer, you must
add it to the certificate file. See “Creating and Managing SSL Certificate Files” on
page 183.
Note: If you do not specify which individual clients can have access, any user with a
distinguished name from an issuer in the Authenticator Name list can have
administrative access to the Broker Server.
Either enter the User Name into the Enter Name field or select one of the User Names
from the Choose Name list.
8 Click Add.
Note: For every client distinguished name that appears in the user name list of the
Access Control tab, the distinguished name of the certificate’s issuer must appear in
the authenticator name list. If not, you must add it to the certificate file used by the
Broker Server. See “Creating and Managing SSL Certificate Files” on page 183.
Access to the client group is now available only to clients whose certificates meet the
requirements of the ACL.
Using SSL for Territories

The Broker Servers for all members of a territory must be configured for SSL. Each Broker
uses its Broker Server’s SSL configuration for outgoing connections and for accepting
incoming connections. For communication within a territory, either all Brokers use SSL or
no Brokers use SSL. You cannot mix the two modes. In the same way, either all Brokers
use encryption or no Brokers use encryption.
Note: A gateway Broker must conform to SSL requirements for communication within a
territory but can differ for communication across the gateway. For example,
authentication may be required within the territory but not across the territory gateway.
To set up SSL for a territory

1 Make sure that the Broker Server for each Broker in the territory is configured for SSL.
For information about configuring Broker Servers, see “Configuring the webMethods
Broker Server for SSL” on page 171.

Using SSL for Territories
2 Open the Territory Information page of one of the Brokers in the territory. See
“Viewing Territory Information” on page 139 for instructions.
3 View Access Control status on the Territory Information table.
4 If the status is Disabled, click it to enable Access Control.
If the status is Not accessible, SSL required, then SSL is not configured. You must
configure SSL before you can set up the ACL. See “Enabling SSL for the webMethods
Broker Server” on page 175 for instructions.
If the status is Not accessible, Identity required, then SSL is configured, but you are not
identified to the Broker Server. You must configure the Broker Administrator identity
settings before you can set up the ACL. See “Configuring Broker Administrator for
6 If necessary, edit the list of distinguished names of issuers who are allowed to provide
authentication.
By default, the authenticator names for all Broker Servers currently associated with
the territory are already in the list. While authentication is required, there are two
reasons to edit the list:
If you want to remove an authenticator name because the Broker Server
associated with it is no longer in the territory.
If you intend to add a member to the territory whose Broker Server does not have
an authenticator name in the list.
Note: If the issuer name does not appear in this list, it is not known to one of the
Broker Servers in the territory. You must place a Trusted Root for that
authenticator into every certificate used by every Broker Server involved in the
territory.
Alternatively, if you are willing to disable authentication and then add or remove
members of the territory, Broker Administrator adjusts the authenticator name list for
you; click Enable Authentication (administrative clients must connect using SSL) again after
the territory is modified.
Note: If you do not specify which individual clients can have access, any Broker
Server with a distinguished name from an issuer in the authenticator name list can
have access to the territory.

By default, the Broker identities list contains all user names associated with Broker
Servers in the territory. While authentication is required, there are two reasons to edit
the list:
If you intend to add a member to the territory whose Broker Server does not have
a user name in the list.
If you want to remove a user name because the Broker Server associated with it is
no longer in the territory.
8 Alternatively, if you are willing to disable authentication and then add or remove
members of the territory, Broker Administrator adjusts the user name list for you;
click Enable Authentication (administrative clients must connect using SSL) again once the
territory is modified.
Once you have listed the appropriate distinguished names in the Authenticator and User
Names lists, the Access Control list for the territory is complete. Access to the territory is
now available only to Brokers on Broker Servers whose certificates meet the requirements
of the ACL. Existing connections among the Brokers in the territory are not immediately
upgraded. Whenever member Brokers have reason to reconnect with each other, the new
connections use authentication and encryption as established for the territory. To force
reconnection, stop and restart each Broker Server associated with the territory.
Using SSL Across Territory Gateways

You can use SSL to provide the authentication and encryption of communication across a
territory gateway. This feature requires that the Broker Server for each gateway Broker be
configured for SSL.
You configure each side of the gateway for SSL independently. Both sides should match in
terms of authentication and encryption. If the two sides differ, the following dependencies
apply:
The Broker Server for each gateway Broker must be configured for SSL. If one side is
not configured for SSL, you cannot have authentication or encryption across the
gateway.
If both Brokers support SSL and if either side requires authentication, the gateway
becomes an SSL connection. When a gateway Broker requires authentication, the
remote Broker must supply its identity; otherwise, the connection fails.
If both Brokers support SSL and if either side requires encryption, the gateway
connection becomes encrypted if both Brokers can meet the required level of
encryption. For example, if Broker A requires U.S. Domestic encryption but Broker B
can support only U.S. Export encryption, the connection fails.
Unless you manage both Brokers, you must perform the configuration in collaboration
with the administrator of the remote Broker. The actions required to configure SSL for a
gateway differ, depending on whether you manage one or both sides.

Using SSL Across Territory Gateways
Enabling SSL If You Control Both Brokers

Access across a territory gateway is controlled by means of an Access Control List. If you
manage both sides of the gateway, make sure Broker Administrator is connected to both
sides.
If both gateway Brokers are displayed in Broker Administrator, this requirement is
met. If not, add to Broker Administrator, the Broker Server that controls the missing
Broker. See “Adding a Broker Server to Broker Administrator” on page 45.
Make sure the Broker Servers for both gateway Brokers are configured for SSL. For
information about configuring a Broker Server for SSL, see “Configuring the
webMethods Broker Server for SSL” on page 171.
If the territory gateway has not already been created, do so now. For information, see
“Configuring a Gateway if You Control Both Brokers” on page 154.
Perform the following steps separately for each of the two Brokers that form the gateway.
To set up SSL for both sides of a territory gateway
1 Open the Gateway Information page for the gateway Broker. See “Displaying
Gateway Information” on page 148 for instructions.
2 In the Gateway Information table, click the linked value to the right of Access Control.
If Broker Administrator is connected to both sides of the gateway, the remote Broker’s
authenticator name and user name for the Broker Server are listed on the Access
Control page.
4 If necessary, replace the distinguished name of the issuer who is allowed to provide
authentication.
By default, the authenticator names for all Broker Servers currently associated with
the territory are already in the list.
Note: If the issuer name does not appear in this list, it is not known to one of the
Broker Servers in the territory. You must place a Trusted Root for that authenticator
into every certificate used by every Broker Server involved in the territory.
The User Names list contains the user name associated with the remote Broker Server.
Once you have listed the appropriate distinguished names in the Authenticator and User
Names lists for both sides of the gateway, the Access Control list for the gateway is

complete. Authentication is now required for all communication across the territory
gateway. The gateway Brokers immediately attempt to re-establish connection. If any of
the information is incorrect, causing an authentication failure, the connection across the
gateway is broken.
Enabling SSL If You Control One Broker

Access across a territory gateway is controlled by means of an Access Control List. When
you configure a gateway that crosses administrative domains (such as between two
companies), it is likely that you will have control over only one of the gateway Brokers. In
such a case, you need to perform the configuration in collaboration with the owner of the
remote Broker.
To set up SSL if you manage one side of a territory gateway

1 Make sure the territory you control is configured for SSL.
For information about configuring a territory, see “Using SSL for Territories” on
page 178.
2 Share the following information with the owner of the remote Broker:
The Trusted Root (authenticator name) used by the Broker Server for the gateway
Broker
Optionally, the distinguished name of the Broker Server’s certificate (user name)
In return, the owner of the remote Broker must provide you with the remote Broker
Server’s Trusted Root (and optional user name).
3 Install the Trusted Root for the remote Broker Server in the certificate file used by the
Broker Server for the local Broker.
For information about installing Trusted Roots and certificates, see “Creating and
Managing SSL Certificate Files” on page 183.
4 If you have not already created the territory gateway, do so now.
For information, see “Configuring a Gateway If You Control One Broker” on
page 157.
5 Once you perform the steps above, you can follow the instructions for setting up SSL
for both sides of a territory gateway on page 181.

Creating and Managing SSL Certificate Files
Gateway SSL and Territory SSL

The use of SSL across a territory gateway is independent of the use of SSL within a
territory. A gateway Broker can use SSL for connections across the gateway while not
using it for connections within the territory, and vice versa. The fact that a Broker client
connects to a Broker using SSL does not imply end-to-end security during communication
with another client on a remote territory.
When a Broker client receives a document, the document contains some information that
can be useful in determining the nature of the path traveled from the remote Broker. The
document’s read-only envelope includes the fields shown in the table below.
Field Description
connectionIntegrity The lowest encryption level encountered from the

remote client to the local Broker. The encryption levels
are U.S. Domestic, U.S. Export, and no encryption (the
field is not set).
pubDistinguishedName The distinguished name of the Broker client that
published the document using an SSL connection.
pubLabel The access label set by a Broker for the client that
published the document.
route The name of each Broker the document passes through,
along with the date and time.
In addition, the publishing Broker client can add a digital signature in the signature field
of the document’s envelope. For more information about envelope fields, see the
appropriate programmer’s reference.

To make use of secure sockets, you must store your certificates in a certificate file. Each
certificate file can store certificates, trusted roots, and uncertified key pairs. An uncertified
key pair is a step on the way to getting a full certificate.
webMethods provides tools that allow you to create certificate files and import them into
the Broker Administrator.
The awcert command allows you to create certificates, modify them, and manage them. In
addition, you can use the Broker Administrator to upload certificate files into the Broker
Administrator.

Uploading Certificate Files Using the Broker Administrator

If you have already created a certificate file, you can use the Broker Administrator to
upload the file into the Broker Administrator.
You can:
Upload a certificate that resides on the same machine as the Broker Administrator.
Upload a certificate that does not reside on the same machine as the Broker
Administrator. You can use this method if you are not allowed to log on to the
machine on which the Broker Administrator resides. This method allows you to
upload the certificate from the machine on which your browser is running.
Uploading a certificate that resides on the same machine as the Broker Administrator

3 On the Identity page, click the Certificates tab.
4 Click Add Certificate from File-system.
5 In the Certificate File field, enter the location of the certificate file. If you want to assign
a different name to this certificate, enter an optional name (.cert suffix will be added
automatically) in the Certificate Name field.
6 On the SSL Password page, type the certificate file password and then click Proceed to
Next Step.
Note: The certificate file must be on the host where the Integration Server and Broker
Administrator run. If the certificate does not yet exist on this host, you can add one by
using the Broker Administrator or the awcert command. See “Using the Certificate
Manager Program (awcert)” on page 185.
Uploading a certificate that resides on your own machine

3 On the Identity page, click the Certificates tab.
4 On the Certificates page, click Upload Certificate.
5 Browse to the directory that contains the certificate you want to upload and click
Upload.

Using the Certificate Manager Program (awcert)

You can use the webMethods Broker certificate manager program, a command line tool
named awcert, to create and manage certificate files. The command awcert has the
subcommands shown in the table below.
Subcommand Purpose
help Print a usage message for awcert to the screen.
For Trusted Roots
import-trust Installs a trusted root in a certificate file. See “Installing Trusted
Roots” on page 186.
list-trust Lists the trusted roots in a certificate file. See “Listing Trusted
Roots” on page 189.
remove-trust Removes a trusted root from a certificate file. See “Removing
Trusted Roots” on page 189.
For Certificates and Certificate Files
certify Installs signed certificates into a certificate file. See “Installing
Certificates” on page 188.
copy Copies certificates and certificate files. See the following sections:
“Copying All Certificates in a Certificate File” on page 191.
“Exporting a Single Certificate” on page 191.
“Changing Certificate Files to an Exportable Format” on

page 192.
export-pkcs12 Exports a webMethods Broker certificate to PKCS12 certificate
format. To export, use the following syntax:
awcert export-pkcs12 source_pkcs12_file password1 -f
dest_pkcs12_file -p password2 -d distinguished_name
import-pkcs12 Imports a PKCS12 certificate. Before importing, the certificate is
converted to the webMethods Broker certificate file format. To
import, use the following syntax:
awcert import-pkcs12 source_pkcs12_file password1 -f
dest_pkcs12_file -p password2
list Lists the certificates in a certificate file. See “Listing Certificates in
the Certificate File” on page 190.
make-new Creates a new key pair and a certificate request. See “Generating
Key Pairs and Certificate Requests” on page 187.

Subcommand Purpose
password Changes the password for a certificate file. See “Changing the
Certificate File Password” on page 193.
remove Removes a certificate from a certificate file. See “Removing
Certificates from a Certificate File” on page 192.
The process of creating and storing certificates uses the following general steps:
1 Create a certificate file and install one or more trusted roots into the file.
2 Create a certificate request.
3 Submit the certificate request to a Certification Authority.
4 Install the signed certificate into a certificate file.
These steps are described in more detail in the following sections.
Installing Trusted Roots

A trusted root is a special certificate issued by a Certification Authority. You must install a
trusted root in your certificate file before you install any certificates in the file. For
additional actions you can perform on trusted roots, see “Additional Operations for
Trusted Roots” on page 189.
To install a trusted root into a certificate file, at the command line, enter this command:
awcert import-trust certificate_file password -f trusted_root
The arguments are defined as:

certificate_file Name of the certificate file. If the file does not exist, awcert
creates it.
password Password for the certificate file.
-f trusted_root Filename of the trusted root. Trusted roots can be in either
binary or text form.
The following example creates the certificate file my_certs using the password mypasswd,
and installs the trusted root contained in the file t_root.
awcert import-trust my_certs mypasswd -f t_root

Generating Key Pairs and Certificate Requests

To get a certificate from the Certification Authority, you need to generate an uncertified
key pair and submit a certificate request. For additional actions you can perform on
certificates, see “Additional Operations for Certificates” on page 190.
To generate a certificate request, at the command line, enter this command:
awcert make-new certificate_file password -d “distinguished_name”
-f request_file [-m key_length]

certificate_file Name of the certificate file.
-d "distinguished_name" Distinguished name for the proposed certificate.
Enclose the distinguished name in quotation marks,
as described in “Using Distinguished Names with
awcert” on page 193.
-f request_file Name to be given to the certificate request file.
-m key_length Key length (optional). The values can range between
1024 (the default) to 2048.
This command creates an uncertified key pair and puts it into the specified certificate file.
The command also generates a certificate request file in PKCS #10 format. PKCS (Public
Key Cryptography Standards) #101 defines a syntax for certificate requests.
The key length determines the level of security provided for the connection; the larger the
key length, the greater the security. Added security comes at the price of performance; the
larger the key length, the more time it takes for encryption and signature verification
operations.
The following example generates a certificate request in the certificate file my_certs using
the password mypasswd. The certificate request file is to be named my_request.
awcert make-new my_certs mypasswd -d
“CN=Client,OU=Eng,O=webMethods,L=Sunnyvale,ST=CA,C=US” -f my_request -m 768
The format of the certificate request is similar to this:

Common-name: Client
Organization Unit: Eng
Organization: webMethods
Locality: Sunnyvale
State: CA
Country: US
1. Information on PKCS #10 is available through RSA Laboratories, a division of RSA Data Secu-
rity, Inc. See http://www.rsasecurity.com/rsalabs/pkcs/pkcs-10

-----BEGIN NEW CERTIFICATE REQUEST-----
[Text deleted]
-----END NEW CERTIFICATE REQUEST-----
The block of text from BEGIN to END inclusive constitutes the certificate request. Submit the
request to the Certification Authority that provides your certificates. Contact your
Certification Authority for submission requirements.
When you receive the certificate from your Certification Authority, it should be another
block of text:
-----BEGIN CERTIFICATE-----
[Text Deleted]
-----END CERTIFICATE-----
The block of text from BEGIN to END constitutes the certificate (include the BEGIN and
END lines shown above). Copy this block into a temporary file to be used when you
install the certificate.
Installing Certificates
In response to a certificate request, the issuing Certification Authority sends you a X.509-
compliant digital certificate. ITU-T Recommendation X.5091 governs the syntax of digital
certificates. You must install the certificate into the same certificate file where you
previously created the uncertified key pair (page 187).
Note: It is possible that the issuing Certification Authority may change the returned
distinguished name. Visually, it appears the same as the original distinguished name; the
difference occurs in the binary form of the name. In this case, the awcert command
prompts you to accept the changed distinguished name.
To add a certificate to your certificate file, at the command line, enter this command:
awcert certify certificate_file password -f cert_text_file

-f cert_text_file Filename for the certificate you have received from a
Certification Authority.
1. International Telecommunication Union recommendations are available through subscription.

See http://www.itu.ch.

The following example adds the signed certificate in the file signed_cert to the certificate
file my_certs using the password mypasswd.
awcert certify my_certs mypasswd -f signed_cert
Additional Operations for Trusted Roots

A trusted root is a special certificate issued by a Certification Authority that is well known
and trusted. Using the certificate manager program, in addition to installing trusted roots
into a certificate file (previously described in “Installing Trusted Roots” on page 186), you
can perform the following actions on trusted roots.
Listing Trusted Roots

To look at the list of trusted roots in the certificate file, at the command line, enter this
command:
awcert list-trust certificate_file password
The following example lists the trusted roots in the certificate file my_certs using the
password mypasswd.
awcert list-trust my_certs mypasswd
The awcert program lists the distinguished names of all trusted roots in the certificate file.
Removing Trusted Roots

To remove a trusted root from a certificate file, at the command line, enter this command:
awcert remove-trust certificate_file password -d "distinguished_name"

-d “distinguished_name” Distinguished name for the trusted root. Enclose

the distinguished name in quotation marks, as
described in “Using Distinguished Names with
awcert” on page 193.
To get the exact text of the trusted root’s distinguished name, use awcert list-trust,
described in “Listing Trusted Roots” on page 189.

The following example removes a trusted root from the certificate file my_certs using the
password mypasswd.
awcert remove-trust my_certs mypasswd -d "OU=Certification
Authority,O=Apex Data Security Inc.,C=US"
Additional Operations for Certificates

A certificate is a digital document verifying that a public key belongs to a given entity.
Using the certificate manager program, in addition to generating key pairs and certificate
requests (previously described in “Generating Key Pairs and Certificate Requests” on
page 187), you can perform the following actions on certificates.
Listing Certificates in the Certificate File

To look at the list of certificates and uncertified key pairs in the certificate file, at the
command line, enter this command:
awcert list certificate_file password [-d "distinguished_name"]
-d “distinguished_name” Distinguished name of the certificate that is to

be listed (optional). Use the -d option to list the
certificate for a single distinguished name.
Enclose the distinguished name in quotation
marks, as described in “Using Distinguished
Names with awcert” on page 193.
The following example lists all certificates and uncertified key pairs in the certificate file
my_certs using the password mypasswd.
awcert list my_certs mypasswd
The following example lists the certificate for a specific distinguished name:
awcert list my_certs mypasswd -d "CN=Client,OU=Eng,O=webMethods,
L=Sunnyvale,ST=CA,C=US"

Copying All Certificates in a Certificate File

To copy all certificates and trusted roots, if necessary, from one certificate file into another,
at the command line, enter this command:
awcert copy source_cert_file password1 -f dest_cert_file -p password2
source_cert_file Name of the source certificate file.

password1 Password for the source certificate file.
-f dest_cert_file Name of the destination certificate file.
-p password2 Password for the destination certificate file.
The following example copies all certificates from the certificate file my_certs using the
password mypasswd to the certificate file other_certs using the password passwd2.
awcert copy my_certs mypasswd -f other_certs -p passwd2
Exporting a Single Certificate

To export certification information associated with a specific distinguished name from one
certificate file into another, at the command line, enter this command:
awcert copy source_cert_file password1 -d “distinguished_name”
-f dest_cert_file -p password2

source_cert_file Name of the source certificate file.
-d “distinguished_name” Distinguished name for the certificate. Enclose the
distinguished name in quotation marks, as described
in “Using Distinguished Names with awcert” on
page 193.
-f dest_cert_file Name of the destination certificate file.
-p password2 Password for the destination certificate file.
To get the exact text of the certificate’s distinguished name, use awcert list, described in
“Listing Certificates in the Certificate File” on page 190.
The following example exports a single certificate from the certificate file my_certs using
the password mypasswd to the certificate file other_certs using the password passwd2.
awcert copy my_certs mypasswd -d “CN=Client,OU=Eng,O=webMethods,L=Sunnyvale,ST=CA,
C=US” -f other_certs -p passwd2

Changing Certificate Files to an Exportable Format

The United States government imposes a restriction on the strength of encryption
algorithms that can be exported out of the country. Encryption strength is usually stated
in bits. The version of webMethods Broker available inside the United States uses 128-bit
encryption. The version of webMethods Broker available for export uses 40-bit
encryption. The United States version of awcert allows you to convert existing certificate
files from the 128-bit format to a 40-bit format.
To create a 40-bit version of a certificate file from the 128-bit version, at the command line,
enter this command:
awcert copy 128-bit_cert_file password1 -f 40-bit_cert_file -p password2 -x

128-bit_cert_file Name of the 128-bit source certificate file.
-f 40-bit_cert_file Name of the new 40-bit certificate file.
-p password2 Password for the 40-bit certificate file.
-x Specifies that the output be in the 40-bit
exportable version.
The following example uses the domestic certificate file my_certs using the password
mypasswd to create the exportable certificate file exp_certs using the password passwd2.
awcert copy my_certs mypasswd -f exp_certs -p passwd2 -x
Removing Certificates from a Certificate File

To remove a certificate from a certificate file, at the command line, enter this command:
awcert remove certificate_file password -d “distinguished_name”

-d “distinguished_name” Distinguished name for the certificate to be
deleted. Enclose the distinguished name in
quotation marks, as described in “Using
Distinguished Names with awcert” on page 193.

The following example removes a certificate from the certificate file my_certs using the
password mypasswd.
awcert remove my_certs mypasswd -d “OU=Eng,O=webMethods,C=US”
Changing the Certificate File Password

To change the password on the certificate file, at the command line, enter this command:
awcert password certificate_file old_password -p new_password

old_password Old password for the certificate file.
-p new_password New password for the certificate file.
The following example changes the password for the certificate file my_certs from
oldpasswd to newpasswd.
awcert password mycerts oldpasswd -p newpasswd
Using Distinguished Names with awcert

In addition to the conventions described in “Distinguished Names” on page 166, you
should follow these rules when entering distinguished names for the awcert command:
Enclose distinguished names in double quotation marks.
If a value within the distinguished name contains one of the characters shown here in
parentheses (, ; = + < > #), enclose the value with double quotation marks (as in
O=”webMethods, Inc.”).
On Windows, you must escape each quotation mark by preceding it with a backslash
(\"). On UNIX (except C shell), you do not have to escape the interior double
quotation marks if you enclose the distinguished name in single quotation marks. On
UNIX C shell, do not escape the interior double quotation marks; instead, enclose the
distinguished name in single quotation marks.
The following examples show the correct punctuation for a distinguished name as it is
used in awcert.
Windows and UNIX (except C shell):
“CN=Client,OU=Eng,O=\”webMethods, Inc.\”,L=Sunnyvale,ST=CA,C=US”
UNIX (including C shell):

’CN=Client,OU=Eng,O=”webMethods, Inc.”,L=Sunnyvale,ST=CA,C=US’

Certificate Status
Each certificate has a status associated with it, as shown in the table below.
Status Value Description

VALID The certificate is valid at the current time.
PENDING The certificate is not yet valid because the beginning date for the
validity period has not yet occurred.
EXPIRED The certificate is no longer valid because the end date for the
validity period has passed.
REVOCATION The status of the certificate is not known. This status typically
UNKNOWN occurs for test certificates.
To display the status of a certificate, use the awcert list command.

Certificate status also appears in the Preferences window when you specify a certificate to
be used when Broker Administrator communicates with a Broker Server. See
“Configuring Broker Administrator for SSL Support” on page 173.
Working with Firewalls

You can implement the webMethods Broker system behind a firewall to help preserve the
integrity of your network. To enable the webMethods Broker system to work through a
commercial firewall, open the port used by the Broker Server (the default is 6849) through
the firewall. Opening the Broker Server’s port enables customers and outside users to run
your webMethods Broker-based applications without compromising network integrity.
The Broker Administrator also use the Broker Server’s port. It is recommended that SSL
be used in conjunction with a firewall to prevent administrative access from the public
network.
Using SSL through Firewalls

The Broker Server requires you to open a main port (the default is 6849) for non-SSL
connections. If the Broker Server supports SSL connections, it also uses two other port
numbers. For SSL connections with no client certificate, use port main-1 (the default is
6848). For SSL connections with a client certificate, use port main-2 (the default is 6847).
You can open all or just some of these ports in your firewall depending on what
capabilities you want to allow.

Using Access Labels
Using Access Labels

Access control in the webMethods Brokeris focused around document types and users. A
Broker client is allowed to publish and subscribe to documents based on the document
type. While this control in the webMethods Broker is expressed and controlled on a per-
document type basis, the webMethods Broker also supports controls at the individual
document level, i.e., content-based rather than type-based. While client subscription
filters limit the document instances a subscriber is interested in receiving, content-based
security limits the document instances that a receiver is allowed to receive. The
webMethods Broker enforces whether the receiver is allowed to receive a given
document; this decision is based on the receiver’s permissions and attributes of a
particular document.
The use of content-based security through access labels introduces the concept of access
control by user in addition to document type. This section describes access labels and the
mechanisms needed to implement them.
User-Based Access
Access control based on document types works well as long as all clients have the same
level of access. When one introduces the need for multiple levels of access, the number of
document types multiplies. For example, assume a document type deleteRecord. To
provide different access to users, based on Confidential, Secret, and Top Secret access
levels, you might need the three document types deleteConfidentialRecord,
deleteSecretRecord, and deleteTopSecretRecord.
The use of content-based security by means of access labels allows a client to label a
document instance as requiring certain permissions. Using this model, the Confidential,
Secret, and Top Secret clients can use the single document type deleteRecord, but each
has a different access label.
Access labels allow you to prevent a Broker client from receiving a document based on the
document's content, hence the term "content-based security.” The publisher labels a
document with its required access rights and Broker enforces access.
Access labels also allow you to provide a receiving Broker client with information about
the publisher's rights. The receiving client uses information in the document to control
access.
The webMethods Broker Implementation

webMethods Broker supports the use of user-based access control:
The Broker supports the concept of a user. The Broker also tracks the user associated
with a given client.
The Broker supports the use of an external process, called an Access Label Adapter
(ALA), to store security information. The Broker contacts the ALA to look up access

rights, called an access label (see “What is an Access Label?” on page 196). The Broker
associates these rights with a client.
Note: webMethods does not include an Access Label Adapter as part of the product.
You must create the adapter yourself.
The Broker places the client's access label into the _env.pubLabel field of all
documents the client publishes. This action provides the receiving Broker client with
information about the publisher's rights.
Publishing clients can set the _env.controlLabel field in documents. When set, only
clients that have the proper access label can receive the documents. Clients have the
option of letting the Broker automatically set this field for them.
Client Ownership
If a client is created on the Broker over an authenticated SSL connection, the Broker
records the client's owning user along with the client. The user name is the distinguished
name (DN) and the authenticator is the issuer DN of the client's SSL certificate.
In a related issue, clients that have an owner allow future reconnection from only those
processes that authenticate as the same user.
What is an Access Label?

An access label is a sequence of unsigned short (16-bit) values. Each value in the sequence
represents an access right. For example:
label[0]=4
label[1]=5
label[2]=0
An access label can also be logically thought of as a bitmask. The access label in the
example describes a bitmask of 6 bits where individual values correspond to bit positions.
In binary form, the bitmask for this example looks as follows, with bit positions 0, 4, and 5
set to 1 (least significant bit to the right):
110001
or hex 0x31. Duplicate values in the label are ignored. Negative values are invalid and will
generate errors.

Using Access Labels
Acquiring an Access Label

If a Broker client is created on the Broker over an authenticated SSL connection, the Broker
automatically requests an access label for the client if an access label adapter is available.
The client's user identity and access label are the same for all sessions (for shared state
clients) of that client.
A client can pass a “hint” (a string) through to the ALA when the client is created. Set the
hint on the BrokerConnectionDescriptor using the following API call:
C : BrokerError awSetDescriptorAccessLabelHint
BrokerConnectionDescriptor desc,
char *hint);
Java : void BrokerConnectionDescriptor.setAccessLabelHint(String hint);
A client can get the value of its access label by using the following API call:
C : BrokerError awGetClientAccessLabel(BrokerClient client,
int *n,
short **label);
Java : short [] BrokerClient.getAccessLabel();
An error is returned if the client does not have a label because:

there is no ALA,
the ALA is down,
the client was not created with an authenticated connection, or
a failure occurred in looking up the label.

Applications that want to be sure they have a label should call this API function before
beginning processing. For more information, see the webMethods Broker Administration
C API Programmer’s Guide or the webMethods Broker Administration Java API Programmer’s
Guide.
How Access Labels Are Used

A client's access label is used in three ways: the source label, the control label, and the
receipt label.
Source Label
The source label contains the access rights of the application that publishes a document.
The Broker fills in the envelope field _env.pubLabel with the publishing client's access
label (if the client has one). This information is not used by the Broker, but receiving
clients can make use of the information.
Clients cannot fill in the _env.pubLabel field themselves in an attempt to spoof their
access rights.

Control Label
The control label contains the access rights required to receive a document. The control
label is stored in the _env.controlLabel envelope field.
The control label cannot contain values not present in the client's access label. For
example, a client with a security level of “Confidential” cannot set a control label with a
level of “Top Secret.” If a client attempts to set a control label containing values not
present in its access label, an error (exception) is returned. Also, clients must have an
access label to be able to set control labels on documents. This concept can be described by
the following function (assuming the labels are treated like a bitmask):
if (control_label & (~access_label) !=0)
//FAIL: error(bad control label);
else
//PASS: accept document
A publishing client is responsible for setting this field using the API. An option is
provided to have the Broker set this field for the client by using the following API call:
C : BrokerError awSetClientAutomaticControlLabel(BrokerClient client,
BrokerBoolean enabled);
Java : void BrokerClient.setAutomaticControlLabel(boolean enabled);
This option is normally disabled. When it is enabled, the Broker places the client's access
label into the _env.controlLabel field of all documents the client publishes that do not
already have the field set.
Receipt Label
For all clients, the receipt label is simply their access label. The Broker compares the control
label of all documents retrieved from the client's queue to the client's access label. Any
document for which the client does not have the right access is deleted.
The client's access label must have all the same rights as in the control label. The client's
access label may have more rights than necessary. This permission check can be described
by the following function (assuming the labels are treated like a bitmask):
if ( ((control_label ^ access_label) & control_label) == 0)
// PASS: send document
else
// FAIL: delete document
If a client does not have an access label, permission checks always fail for documents with
control labels.
Note: Note that the permission check happens only when the Broker pulls documents from
the queue. The check does not occur when documents are placed into the queue.

Using Access Labels
The Access Label Adapter (ALA)

The ALA is a C or Java API program using a client on the system-defined
“accessLabelAdapter” client group. The ALA does not need any subscriptions. The
“accessLabelAdapter” client group has a Destroy on Disconnect life cycle and a Volatile
storage type. You can modify the access control list (ACL) of the client group so that ALAs
can authenticate using SSL; otherwise, you cannot modify the client group.
The primary function of the ALA is to receive label lookup documents from the Broker
and to reply with access labels. An optional secondary function is to update or revoke
access labels the Broker already has.
The ALA must be connected to a single Broker. In a territory, each Broker with clients
requiring access labels must have its own ALA.
ALA Communication
The Broker and ALA communicate using system-defined document types. All document
types described are Volatile with infinite time-to-live.
// Sent from Broker to ALA. ALA replies with
// Broker::ALA::label or Broker::ALA:error
Broker::ALA::lookup {
unicode_string user;
unicode_string authenticator;
unicode_string serial;
unicode_string hint;
};
// Sent from ALA to Broker, in response to

// Broker::ALA::lookup.
Broker::ALA::label {
short label[];
};
// Sent from ALA to Broker, in response to

// Broker::ALA::lookup.
Broker::ALA::error {
unicode_string error;
unicode_string detail;
};

// Sent from ALA to Broker.

Broker::ALA::change {
unicode_string serial;
short label[];
};
The ALA can use the Broker::ALA::error document to report problems during label
lookup. The error field should be one of the following:
Error Field Meaning

unknown The user is not known to the ALA.
internal A temporary failure has occurred. If the client has an existing
label, it is not invalidated.
If the error string is not internal, the current access label is invalidated (e.g., cleared).
You can use the detail field to record an implementation-specific error message. If the detail
field is present, the Broker logs an error for the failure. In error cases, any pending
lookups for the user's label will fail. If there is a non-empty detail string, it is logged to the
Broker Server’s error log.
The ALA can use the change document to update an access label the Broker already
knows about. You can effectively revoke a label by updating with a zero-length label. The
client is not notified when its access label changes.
The Broker delivers documents to the ALA client (that is to say, the _env.destId field is
set). The ALA should confirm that _env.pubId is set to //broker-name.
The ALA should deliver documents to the Broker using //broker-name as the destination
ID. The Broker ignores published ALA documents, as well as documents not delivered
from a local member of the “accessLabelAdapter” client group.

Using Access Labels
Error Handling
The Broker takes action depending on the ALA failure mode:
Failure Mode Broker Action
ALA is not running (not Requests for client access labels fail until the ALA is
connected) running again.
ALA does not respond Pending access label lookups fail after waiting 10
seconds for an ALA reply. Clients that already have
access labels continue to function.
In the future, the Broker may disconnect the ALA if the
ALA does not respond to any requests for one minute.
This might help get the ALA restarted
ALA disconnects If an ALA disconnects, it will likely not respond within
the 10 second time-out and requests to it will be treated
as such.
ALA supplies invalid replies The ALA could reply to a lookup with an unknown DN,
or invalid access label (for example, negative label
values). Some invalid replies will be ignored, and some
will result in the failure of an access label lookup.
Regardless, the Broker will log each failure by the ALA.
Multiple ALAs running The Broker uses the first ALA to connect; it ignores the
other ALAs until the first one disconnects.
The Access Label Process

1 Configure the Broker.
The Broker uses clients connected to the system-defined client group
“accessLabelAdapter” for access label lookups. You can use an Access Control List
(ACL) on the client group to restrict access to trusted adapters.
2 Start the Access Label Adapter (ALA).
Each Broker in a territory has its own ALA. Brokers do not use each other's ALAs.
However, one adapter instance can support multiple Brokers by connecting to each one.
Client group replication helps support this usage by distributing the ACL. It is up to you
to maintain consistency across multiple instances of the ALA.
The adapter does not need to make any subscriptions.
In a trusted system, the adapter should use SSL and have a certificate that matches one
listed in the client group ACL.
3 Create the Broker client.

The creation of the client includes an application-defined “hint” string.

4 The Broker asks for an access label.
The Broker builds a Broker::ALA::lookup request document to get an access label
for the client. The document includes the client user information (DN and issuer DN)
and the application defined “hint” string.
The Broker delivers the document to one of the connected ALAs.
If there are no ALAs running on the Broker, the lookup fails and the client does not
get an access label.
5 ALA returns an access label.
The ALA can make one of two responses to each label request: an access label or an
error.
A successful response (Broker::ALA::label) includes the access label.
A failure response (Broker::ALA::error) includes an error type, DN, and
optional error detail.
A response takes the form of a document delivered to the local Broker.
The ALA should be coded to ignore documents not from the local Broker (for
example: check that_env.pubId is equal to "//brokername").
The ALA should send its reply using awDeliverReplyEvent (or the equivalent Java
API function) to make sure the envelope is properly set up. If the ALA does not use
this function, the _env.tag field from the Broker::ALA::lookup document will not
be copied over, and the result of the lookup will affect all outstanding lookup requests
for that client's owning user.
The ALA should also copy the user and authenticator values from the request to the
response. If the ALA does not copy these values, no clients will receive the labels.
6 The Broker gets a response from the ALA.
The Broker handles each kind of ALA response:
ALA Response Broker Action

Broker::ALA::label The Broker assigns the access label to the requesting
client if this document includes a tag. If the tag is not
set, any clients with pending requests for that user
(DN and issuer DN) are updated.
Broker::ALA::error Any clients with pending requests for that user (DN
and issuer DN) get a failure code.

Using Access Labels
Expiration of Labels
Labels do not expire. They stay valid until the ALA reports a new label value for the
client's owning user by means of a Broker::ALA::change document.
The Broker does attempt to refresh the client's access label each time the client reconnects.
For shared-state clients, this happens each time the number of connected clients goes from
zero to one.
If an ALA wants to expire labels, it may do so by issuing Broker::ALA::change
documents, using its own expiration policy. Note that change documents apply to all
clients with a matching distinguished name and issuer distinguished name pair.
Broker-to-Broker
Document access labels are preserved unchanged between Brokers and across territory
gateways. To maintain security, all interconnected Brokers and territories should share
the same meaning for access label values.


CHAPTER 12
Configuring Administered Objects with the JMS
Administrator
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Configuration Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Starting the JMS Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Configuring the JNDI Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Selecting a Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Creating and Managing JMS Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

CHAPTER 12 Configuring Administered Objects with the JMS Administrator
Overview
This chapter describes how to configure administered objects using the webMethods JMS
Administrator. You can also manage administered objects using the webMethods
JMSAdmin command line tool or programmatically. For more information, see the
Configuration Tasks
Configuring administered objects with the JMS Administrator involves the following
steps:
1 Selecting the JNDI provider that will bind JMS objects.
2 Selecting the Brokers to use for JMS messaging.
3 Creating and configuring JMS administered objects, which include:
Topic connection factories and topics (for publish/subscribe messaging models)
Queue connection factories and queues (for point-to-point messaging models)
Starting the JMS Administrator

To start the JMS Administrator, you need the following:
A browser.
The URL for the JMS Administrator, including the host name and port number of the
Integration Server to which you are connecting.
A valid user name and password with administrator privileges.
To log on to the JMS Administrator
1 Start the Integration Server on which the JMS Administrator runs, the server on which
the JNDI provider resides, and the Broker on which to store JMS Provider
configuration settings.
2 Open a browser window and point the browser to the host and port on which the
Integration Server is running.
Examples:
If the Integration Server on which the JMS Administrator resides is using the default
port, you would type:
http://hostname:5555/WmJMSAdmin/

Configuring the JNDI Provider
If the Integration Server is running on port 4040 on a machine called ATLAS, you
would type:
http://ATLAS:4040/WmJMSAdmin/
3 Log on to the JMS Administrator with a user name and password that has
administrator privileges.
If you have not changed the default webMethods Integration Server user name and
password, you can use the following default values:
User Name: Administrator
Password: manage
User names and passwords are case sensitive.
Note: It is strongly recommended you change the default password immediately after
installing webMethods Integration Server, since this password is publicly available.
For information about changing the password, see the webMethods Integration Server
Administrator’s Guide.
Note: If the Integration Server is not running, your browser will issue an error similar
to the following:
Cannot open the Internet site http://hostname:5555/WmJMSAdmin/.
A connection with the server could not be established.

This section describes how to select and configure a JNDI provider to store administered
objects. There are two methods:
Select an available JNDI provider and use its default settings, or customize the
provider settings.
Upload a text file containing the properties for the JNDI provider to the Integration
Server.
Note: In order for the JMS Administrator to store administered objects on a server (for
example, WebLogic, LDAP, or JBoss), the server must be active. For LDAP servers, the
server must either be running with schema validation turned off or it must have the Java
object schema installed. The Java object schema is defined in RFC 2173.
If you are using the webMethods JMS Naming Service as the JNDI provider, make sure
the Broker acting as the naming server is running.

To select and customize a JNDI provider using the JMS Administrator
1 From the Settings area of the Navigation panel, click JNDI.

2 On the Settings > JNDI page, click Change JNDI Settings.
3 On the Settings > JNDI > Change page, complete the following fields:
In this field... Select or type...

Predefined JNDI Templates The type of JNDI provider you want to use.
The JMS Administrator provides templates for some
common JNDI providers. These templates help you
complete the Initial Context Factory and Provider URL
fields for a specific provider. You can either select a
template from this list or specify a different type of
JNDI provider.
To specify a different provider, or to change the
settings of a provider you have already selected, leave
this field set to Current Settings.
Initial Context Factory The class name of the JNDI provider. If you selected a
predefined JNDI template, this field is already
completed.
Provider URL The URL of the session’s initial context (that is, the
JNDI directory in which to store JMS administered
objects). If you selected a predefined JNDI template,
replace the information in brackets with information
appropriate for your site.
Security Principal The principal name that the JMS Administrator
provides to the JNDI provider, if the provider requires
one for accessing the JNDI directory.
For information about whether a JNDI provider
requires a principal name, see the product
documentation for the provider.
Security Credentials The credentials that the JMS Administrator provides
to the JNDI provider, if the provider requires security
credentials to access the JNDI directory.
requires security credentials, and the format, see the
product documentation for the provider.


Other Properties Any additional properties the JNDI provider needs to
configure the JNDI. If you selected a predefined JNDI
template, this field is already completed for you.
requires additional properties, see the product
documentation for the provider.
Jar Files and Classes The CLASSPATH of any additional JAR and class files
the JNDI provider needs to connect to the JNDI. These
files must reside in a file system that is accessible to
the Integration Server.
For more information about the JAR files and
supporting classes a JNDI provider requires, and the
location of the files, see the product documentation for
the provider.
Uploading a JNDI Properties File

This configuration method allows you to select a completed properties file written in text
format for upload to the Integration Server.
If you use this method, refer to the JNDI provider documentation for descriptions of the
properties. Information about properties for the webMethods JMS Naming Service is
available in the webMethods Broker JMS Provider Programmer’s Guide.
To upload an existing JNDI properties file
1 From the Settings area of the Navigation panel, click JNDI.

2 On the Settings > JNDI page, click Upload JNDI Properties File.
3 In the Properties File field, type the fully qualified name of the JNDI properties file, or
click Browse to locate the file.
4 Click Upload.
When you use a properties file to configure the webMethods JMS Naming Service, you
must take additional steps to add the JNDI class file to the Integration Server that hosts
JMS Administrator package. Once you have performed the procedure below, you will not
need to repeat it.
Note: If you are using the webMethods JMS Naming Service, then the JNDI class file is:
wmjmsnaming.jar.

To add the JNDI class file to the Integration Server (webMethods JMS Naming Service Provider only)
1 In the Jar Files and Classes on the Settings > JNDI > Change page, specify the absolute
path to the JNDI jar file(s) that you copied to the Integration Server’s file system
before you started this procedure.
Selecting a Broker
This section describes how to:
Select a Broker on which to create JMS Provider configuration settings.
Remove a Broker from the list of Brokers that are used to create JMS Provider
configuration settings.
Change the Broker timeout value. This timeout value determines how long the JMS
Administrator should wait for a connection to the Broker when updating the Broker
with structures needed to support your JMS client.
Identify the certificate, distinguished name, and password the JMS Administrator
uses to access the Broker, for Broker Servers that are SSL enabled. This identification
is needed for administrative access to Brokers if they are protected by Access Control
Lists (ACLs).
Note: The JMS Administrator user interface uses the term “Broker” to refer to the Broker
through which your JMS clients will exchange messages.
To select a JMS Broker
1 From the Settings area of the Navigation panel, click JMS Brokers.
2 On the Settings > JMS Brokers page, click Add a JMS Broker.
3 On the Settings > JMS Brokers > Add page, complete the following fields:
In this field... Select or type the...

JMS Broker Name (Optional) Name of the Broker. If you do not
specify a JMS Broker name, the JMS Administrator
uses the default Broker on the specified Broker
Server.

Selecting a Broker

JMS Broker Server Host name of the Broker Server on which the
Broker resides.
Port Port number of the Broker Server on which the
Broker resides.
4 Click Add.
The Settings > JMS Brokers page displays the Broker you added, indicates whether the
Broker is currently connected, and indicates whether the Broker Server to which the
Broker is connected is SSL enabled.
Tip! You can sort the list of Brokers by clicking the Broker Name column heading.
To remove a JMS Broker
2 On the Settings > JMS Brokers page, click Remove one or more JMS Brokers.
3 On the Settings > JMS Brokers > Remove page, do one of the following:
To... Click the...

Specify one or more JMS Brokers Check box next to each JMS Broker you want
to remove to remove.
Remove all JMS Brokers All/None check box.
Tip! You can clear the list by first clicking the All/None check box (to select all check
boxes) and then clicking All/None again (to clear all check boxes).
4 Click Remove.
5 When prompted to confirm that you want to remove the selected JMS Brokers, click
OK.
To change the timeout value for a Broker
2 On the Settings > JMS Brokers page, click JMS Broker Settings.
3 On the Settings > JMS Brokers > Timeout page, click Change JMS Broker Timeout.

4 In the JMS Broker Timeout field, type the number of seconds to wait for a connection to
the JMS Broker.
To change SSL settings for a Broker
2 On the Settings > JMS Brokers page, click Edit SSL Settings next to the Broker whose SSL
settings you want to change.
3 On the SSL page, complete the following fields:

Certificate Path and file name of the file that contains the
digital certificate that the JMS Administrator
submits to the Broker when it makes a connection.
This certificate must reside in a file system that is
accessible to the Integration Server.
Distinguished Name A distinguished name (that is, the portion of a
certificate that identifies the owner of the
certificate) that matches the ACL for the Broker.
For example:
CN=John Smith,OU=Engineering,
O=Company,L=Sunnyvale,ST=CA,C=USA,
EM=jsmith@company.com
Password The password used to authenticate access to the
Broker.
4 Click Set.
Creating and Managing JMS Objects

This section describes how to create, display, modify, and delete the following JMS objects
using the JMS Administrator:
Connection factories. Connection factories allow you to define a set of parameters that a
JMS client can recall at runtime to create connections to the JMS Provider. Connection
factory objects include queue connection factories and topic connection factories.
Destinations. Destination objects are queues (in a point-to-point or PTP messaging
model) and topics (in a publish/subscribe messaging model).

The steps in this section assume that you have already specified the JNDI provider and
Broker with which to associate these JMS objects and their configuration settings. If you
have not done so, refer to “Configuring the JNDI Provider” on page 207 and “Selecting a
Broker” on page 210.
Note: When naming JMS objects and subcontexts in an LDAP environment, you must
include a prefix, such as cn= (common name), or ou= (organizational unit). The JMS
Administrator simplifies the use of LDAP service providers by allowing you to refer to
object and context names without a prefix. If you do not supply a prefix, the JMS
Administrator automatically adds a default prefix.
Important! Before you create or modify a connection factory or destination, make sure the
Broker that will store the JMS provider’s configuration settings is started. If the Broker is
not started, the JMS Administrator will not be able to create the object.
The Broker does not have to be started to view or remove a JMS administered object once
that object is created.
Administering Queue Connection Factories

Create a queue connection factory.
View information about a queue connection factory.
Modify a queue connection factory.
Remove a queue connection factory.
To create a queue connection factory
1 Make sure the Broker that will store the JMS Provider configuration settings is active.
2 From the JMS area of the Navigation panel, click Connection Factories.
3 On the JMS > Connection Factories > Create page, complete the following fields:


Lookup Name Enter the name of the JNDI directory in which to
bind this connection factory.
Factory Type Select either QueueConnectionFactory (for
implementing non-transactional connections) or
XAQueueConnectionFactory (for implementing
transactional connections) from the list.
Client ID (Optional) The base client ID for connections
created by this factory.
If you do specify a client ID, the connection
factory derives a client ID from this value each
time a connection is established.
If you do not specify a client ID, the connection
factory assigns a unique client ID when a
connection is established.
JMS Broker Select a Broker address from the list.
This address is stored with the connection factory
object so that JMS applications retrieving the
object from JNDI connect to the correct Broker.
SSL Keystore Path and file name for the keystore file that
contains the certificate information for SSL
connections.
SSL Encryption Whether traffic to the Broker on this queue
connection will be encrypted. The default is No.
If set to Yes, all traffic to the Broker on this
queue connection will be encrypted.
If set to No, the connection will be
authenticated but no data will be encrypted.
Client Group Enter the name of an existing client group or a new
client group for this connection factory. If a new
client group name is entered, that client group is
created.
4 Click Create.

To view information about a queue connection factory

2 On the JMS > Connection Factories page, in the Connection Factories table, click the
lookup name of the queue connection factory you want to view.
Tip! You can sort the list of connection factories by clicking the Lookup Name column
heading.
The JMS Administrator displays the following information about the queue
connection factory:
Field Description
Lookup Name The name of the JNDI directory to which this connection
factory is bound.
Class The class of the queue connection factory as it was bound
into JNDI.
Type Whether the connection factory is a queue or topic type,
and whether it is transactional or non-transactional.
Client ID The base client ID for connections created by this factory.
If a client ID is specified, the connection factory
derives a client ID from this value each time a
connection is established. If this ID is already in use,
subsequent queue connections will append a numeric
suffix to the client ID to make it unique.
If a client ID is not specified, the connection factory
assigns a unique client ID whenever a connection is
established.
JMS Broker The name of the Broker to which queue connections will
be established.
To view details about this Broker, click its name.
SSL Certificate Filename Path and file name of the file containing the SSL certificate
information.
SSL Encryption Indicates whether traffic to the Broker on connections
created from this connection factory will be encrypted
(yes) or unencrypted (no).

Field Description
Client Group The name of the client group associated with this
connection factory. To view details about this client
group, click its name.
Permissions Displays as a set of yes/no switches whether this
connection factory can send or receive messages to the
queues in the list (Broker event types). The event type
name associated with queues is the queue name prefixed
with JMS::Queues, for example:
JMS::Queues::QueueA
To modify a queue connection factory
lookup name of the queue connection factory you want to modify.
3 On the JMS > Connection Factories > ConnectionFactory page, click Modify Connection
Factory.
4 Modify the client ID, JMS Broker, SSL encryption, client group, and permissions.
5 Click Modify.
To remove a queue connection factory
2 On the JMS > Connection Factories page, click Remove Connection Factories.
3 On the JMS > Connection Factories > Remove page, do one of the following:
To... Click the...

Specify one or more connection Check box next to each connection factory
factories to remove you want to remove.
Remove all connection factories All/None check box.
4 Click Remove.
5 When prompted to confirm removal of the selected connection factories, click OK.

Administering Queues
Create a queue.
View information about a queue.
Modify a queue.
Remove a queue.
Remove a queue for a queue receiver.
To create a queue object
1 Make sure that the Broker that will store the JMS configuration settings for the queue
object is started.
2 From the JMS area of the Navigation panel, click Destinations.
3 On the JMS > Destinations page, click Create a Queue.
4 If you want to change the default connection sharing and encryption settings, click
Show Advanced Settings.
5 Complete the following fields:

Lookup Name The name of the JNDI directory in which to bind this
queue.
Queue Name The name of the queue. You can either type a fully
qualified name (for example,
/territory/broker/queuename) or a partial name.
Use the following naming guidelines:
The name cannot exceed 255 byes.
The first character of the name cannot be #.
The name cannot contain the following characters:

@ / or :


Shared State (Advanced Whether to allow multiple connections to share the
Settings only) same connection client ID. The default is No.
If Shared State is set to Yes, the JMS Administrator
creates Broker clients as shared state clients for the
queue connection.
Note: If you selected WebLogic as your JNDI provider,

set this field to Yes. Setting this field to Yes allows the
message-driven bean listener that runs on the
WebLogic application server to create the associated
queue clients. It also enables the message-driven
beans to receive messages.
Shared State Ordering The ordering of documents received on a shared state

(Advanced Settings only) client. The default is none.
To receive documents in order from a publisher,
set to publisher.
To receive documents in any order, set to none.
6 Click Create.
To view information about a queue

2 On the JMS > Destinations page, in the Destinations table, click the lookup name of the
queue you want to view.
Tip! You can sort the list of queues by clicking the Lookup Name or Destination Name
column headings.
The JMS Administrator displays the following information about the queue:
Field Description
Lookup Name The name of the JNDI directory to which this queue is
bound.
Class The class of the queue as it was bound into JNDI.
Type The type of destination (queue or topic).
Queue Name The name of the queue.

Field Description
Event Type The fully qualified Broker Event Type (scope and base
name) associated with this queue.
Client Group The group that queue receivers use to establish a
connection to the Broker.
Shared State Whether multiple connections can share the same
connection client ID.
Shared State Ordering The ordering of documents received on a shared state
client (in any order or in order from a publisher).
To modify a queue

2 On the JMS > Destinations page, in the Destinations table, click the queue you want to
modify.
3 On the JMS > Destinations > QueueName page, click Modify a Destination.
4 Modify the destination’s queue name and shared state settings as described in
“Administering Queues” on page 217.
5 Click Modify.
To remove a queue

2 On the JMS > Destinations page, click Remove Destinations.
3 On the JMS > Destinations > Remove page, do one of the following:
To... Click the...

Specify one or more destinations Check box next to each destination you want
Remove all destinations All/None check box.
4 Click Remove.
5 When prompted to confirm removal of the selected destinations, click OK.

Administering Topic Connection Factories

Create a topic connection factory.
View information about a topic connection factory.
Modify a topic connection factory.

Remove a topic connection factory.
To create a topic connection factory
1 If the Broker that will store the JMS Provider configuration settings is not active, start
it.
3 On the JMS > Connection Factories > Create page, complete the following fields:

Lookup Name Enter the name of the JNDI directory in which to
bind this connection factory.
Factory Type Select either TopicConnectionFactory (for
implementing non-transactional connections) or
XATopicConnectionFactory (for implementing
transactional connections) from the list.
If you do specify a client ID, the connection
factory derives a client ID from this value each
time a connection is established.
If you do not specify a client ID, the connection
factory assigns a unique client ID when a
connection is established.
JMS Broker Select a Broker address from the list.
This address is stored with the connection factory
object so that JMS applications retrieving the
object from JNDI connect to the correct Broker.
SSL Keystore Path and file name for the keystore file that
contains the certificate information for SSL
connections.


SSL Encryption Whether traffic to the Broker on connections made
from this connection factory will be encrypted.
The default is No.
If set to Yes, all traffic to the Broker on this
connection will be encrypted.
If set to No, the connection will be
authenticated but no data will be encrypted.
Client Group Enter the name of an existing client group or a new
client group for this connection factory. If a new
client group name is entered, that client group is
created.
4 Click Create.
To view information about a topic connection factory
lookup name of the topic connection factory you want to view.
Tip! You can sort the list of connection factories by clicking the Lookup Name column
heading.
The JMS Administrator displays the following information about the connection
factory:
Field Description
Lookup Name The name of the JNDI directory to which this topic
connection factory is bound.
Class The class of the topic connection factory object as it
was bound into JNDI.
Type The type of connection factory (topic or queue).

Field Description
If you specify a client ID, the connection
factory derives a client ID from this ID each
time a connection is established. If this ID is
already in use, subsequent topic connections
will append a numeric suffix to the client ID to
make it unique.
If you do not specify a client ID, the
connection factory assigns a unique client ID
when a connection is established.
JMS Broker The name of the Broker to which topic connections
will be established.
You can view details about this Broker by clicking
its name.
SSL Certificate Filename Path and file name of the file containing the SSL
certificate information.
SSL Encryption Whether traffic to the Broker for connections made
from this connection factory will be encrypted.
Client Group The name of the client group associated with this
connection factory.
To view details about this client group, click its
name.
Permissions Displays as a set of yes/no switches whether this
connection factory can publish or subscribe to the
topics in the list (Broker event types). Every topic
has an associated event type of the same name.
To modify a topic connection factory
lookup name of the topic connection factory you want to modify.
3 On the JMS > Connection Factories > ConnectionFactory page, click Modify Connection
Factory.
4 Modify the connection factory’s client ID, Broker address, SSL encryption, and client
group as described in “Administering Topic Connection Factories” on page 220.

5 In Permissions, select the appropriate check boxes for each Event Type (topic) to
indicate whether the topic connection factory can publish on the topic or subscribe to
the topic.
Note: These check boxes do not display if the Broker is inactive.
6 Click Modify.
To remove a topic connection factory
2 On the JMS > Connection Factories page, click Remove Connection Factory.
3 On the JMS > Connection Factories > Remove page, do one of the following:
To... Click the...

Specify one or more connection Check box next to each connection factory
factories to remove you want to remove.
Remove all connection factories All/None check box.
4 Click Remove.
5 When prompted to confirm that you want to remove the selected connection factories,
click OK.
Administering Topics
This section lists the steps needed to:
Create a topic.
View information about a topic.
Remove a topic.
To create a topic
1 If the Broker that will store the queue is not active, start it.

3 On the JMS > Destinations page, click Create a Topic.

4 If you want to remove the topic prefix or use a topic prefix other than JMS::, click
Show Advanced Settings.
5 Complete the following fields:

Lookup Name The name of the JNDI directory to which to bind
this topic.
Topic Name A valid topic name or wild card (for example, *).
Use the following naming guidelines:
The name cannot exceed 255 byes.
The name must begin with an alphabetic

character, followed by any combination of
alphanumeric characters and underscores (_).
If you clicked Show Advanced Settings, do one of the
following:
If you want to use a topic prefix other than
JMS::, type the new prefix before the topic
name. Separate the prefix from the topic name
with a double colon (::).
If you want to remove the topic prefix, delete
JMS:: before you type the topic name.
Shared State (Advanced Settings Whether to allow multiple connections to share
only) the same connection Client ID. The default is No.
If Shared State is set to Yes, the JMS Administrator
creates as shared state clients:
Broker clients for the topic connection
Broker clients for durable subscribers created

from the connections the topic connection
factory creates
Shared State Ordering (Advanced The ordering of messages received on a shared
Settings only) state client. The default is none.
To receive messages in order from a publisher,
set to publisher.
To receive messages in any order, set to none.
6 Click Create.

To view information about a topic

2 On the JMS > Destinations page, in the Destinations table, click the lookup name of the
topic you want to view.
Tip! You can sort the list of topics by clicking the Lookup Name or Destination Name
column headings.
The JMS Administrator displays the following information about the topic:
Field Description
Lookup Name The name of the JNDI directory to which this topic is
bound.
Class The class of the topic object as it was bound into JNDI.
Type The type of destination (queue or topic).
Topic Name The name of the topic.
Event Type The fully qualified Broker Event Type (scope and base
name) associated with this topic.
Shared State Whether to allow multiple connections to share the
same connection Client ID. The default is No.
Shared State Ordering The ordering of messages received on a shared state
client. The default is none.
To remove a topic

2 On the JMS > Destinations page, click Remove Destinations.
3 On the JMS > Destinations > Remove page, do one of the following:
To... Click the...

Specify one or more destinations Check box next to each destination you want
Remove all destinations All/None check box.

4 Click Remove.
5 When prompted to confirm that you want to remove the selected destinations, click
OK.

PART V
Reference
webMethods Broker Command Line Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Tips and Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

APPENDIX A
webMethods Broker Command Line Utilities
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
server_conf_backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
server_conf_restore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
server_config add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
server_config create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
server_config delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
server_config help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
server_config list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
server_config remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
server_config start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
server_config stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
server_config storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
server_config update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
broker_buildall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
broker_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
broker_delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
broker_load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
broker_ping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
broker_save . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
broker_stop and broker_start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
broker_status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

appendix A webMethods Broker Command Line Utilities
Overview
This appendix describes the Broker Server and Broker command line utilities.
Broker Server Commands

Use the server_config command line program to create and configure Broker Servers.
Run this program on the same host where the Broker Server resides (with the exception of
the list subcommand, which lists known Broker Servers on any host).
Syntax
server_config subcommand [options ...]
The subcommands for server_config are shown in the table below.
server_config Sub Commands Description Page

add Add an existing Broker Server or creates a 236
new one.
create Create a new Broker Server. 237
delete Delete a Broker Server including all its data 245
files.
help Display help commands. 246
list List known Broker Servers. 246
remove Remove a Broker Server but retains all its 247
data files.
start Start a specified Broker Server. 247
stop Stop a specified Broker Server. 247
storage Configure storage sessions for a specified 248
Broker Server.
update Update an existing Broker Server. 252
With the exception of the list, start, and stop subcommands, all subcommands require
that you provide the location of the Broker Server’s data directory. The location of this

Overview
directory is dependent on the platform. When you install webMethods Broker, the data
directory for the Broker Server has the following location:
On this platform: The default data files are located here:
Windows C:\Program
Files\webMethods6\Broker\data\awbrokers65\default
UNIX /var/opt/webmethods/awbrokers65/default
When you create a Broker Server, you provide the pathname of the data directory for that
Broker Server.
Each Broker Server is identified by its main port number (6849 by default), which must
not conflict with ports used by a different Broker Server. If the Broker Server supports SSL
connections, it also uses the port numbers main-1 and main-2. If you attempt to create or
update a Broker Server using a port number that is already being used by existing Broker
Servers, server_config issues an error message.
Note: The server_config command line program is not compatible with previous
versions of webMethods Broker. To configure a Broker Server version 6.1 or earlier,
please refer to the documentation for that version of the product.
Broker Server Configuration Storage Backup Commands

The Broker Server configuration storage back up and restore commands are shown in the
table below.
server_config Sub Commands Description Page

server_conf_backup Creates a backup of the Broker Server’s 232
configuration data storage while the Broker
Server is still running.
server_conf_restore Restores a Broker Server’s configuration 234
data storage from a previous backup
created by server_conf_backup.

Broker Commands
Broker commands are shown in the table below:
Command Description Page

broker_buildall Compiles all intelligent integration components and 253
scripted operations on a Broker.
broker_create Creates a new Broker. 254
broker_delete Deletes a Broker. 256
broker_load Imports Broker data from a file to a Broker. 257
broker_ping Sends system ping documents through a Broker. 259
broker_start Starts the Broker Server. 262
broker_status Displays statistics from the command line for a 265
specific Broker.
broker_stop Stops all Brokers running on the Broker Server, halts 262
all document delivery, and disconnects all clients.
server_conf_backup
Use the server_conf_backup command line tool to back up the Broker Server
configuration data storage. For instructions, see “Backing Up from the Command Line”
on page 86. The server_conf_backup command creates a zip file that the
server_conf_restore tool later uses to restore the backed-up configuration data storage.
For more information about using both the server_conf_backup and

server_conf_restore tools together, see “Backing Up and Restoring System
Configuration Data Storage” on page 85. For more information about the
server_conf_restore command line tool, see “server_conf_restore” on page 234.
Note: The server_conf_backup command line tool is an online backup tool designed to
be used with a running Broker Server.
Syntax
server_conf_backup backup-filename [-h hostname:port] [-k SSL-keystore-filename
–p SSL-password –n SSL-distinguished-name] [-e] [-o] [-v]

server_conf_backup
Arguments
Argument Description
backup-filename Fully qualified path to the name of the file where the
backup is stored. A .zip file extension is added if the
extension is not present.
Example 1: /var/backups/server-6849.zip
OR
Example 2: c:\Backups\server-6849.zip
Note: If the file you specify does not exist, the command
creates it for you. If you have an existing file, then you must
use the -o option to overwrite it.
-h hostname:port The hostname and port of the server you wish to backup.
The default is localhost:6849, but you use this option to
backup other servers on the local machine.
Example: -h localhost:8849
-k SSL-keystore-filename The SSL parameters needed to access the server.
–p SSL-password
–n SSL-distinguished-name SSL-keystore-filename is the name of the file containing the
SSL certificates
SSL-password is the password to access the file.
SSL-distinguished-name is the name used to access the
server.
-e Turns on encryption to the Broker Server.
-o If you have an existing destination file you must use this
command to overwrite it. If this value is not specified and
the file exists, the backup is cancelled with an error
message.
-v Verbose mode. Prints out information about the progress
and completion of the backup.

server_conf_restore
Use the server_conf_restore command line tool to restore the Broker Server
configuration data storage. For instructions, see “Restoring System Configuration Using
the server_conf_restore Command Line Tool” on page 87. The server_conf_restore
tool restores the configuration data storage by copying the backed-up configuration data
files from a prior server_conf_backup to those files’ original locations. The absolute
paths to the configuration data files are captured in the backup zip file created by the
server_conf_backup tool.
For more information about using both the server_conf_backup and

server_conf_restore tools together, see “Backing Up and Restoring System
Configuration Data Storage” on page 85. For more information about the
server_conf_backup command line tool, see “server_conf_backup” on page 232.
Note: The Broker Server configuration data restore feature provides a level of recovery
from Broker storage corruption problems only. This backup/restore feature is not
designed for point-in-time recovery due to user or system errors.
Important! Regardless of the condition of the Broker Server's run-time data (corrupted or
uncorrupted) storage, the backup/restore feature only aids in the recovery from Broker
Server's configuration data storage corruption. It is highly risky to restore the Broker
Server's configuration data storage without removing its run-time data storage because
of potential data inconsistencies between the two storage sessions.
You must remove the existing run-time data files ending in”.qs.stor” and .”qs.log” (not
the “.qs” file), during the recovery process. You should remove the Broker Server's run-
time data storage either before running the server_conf_restore command or after
running the server_conf_restore command and before restarting the Broker Server.
Syntax
server_conf_restore backup-filename [-o] [-v]

server_conf_restore
Arguments
backup-filename The name of the file where the backup is stored.
Example 1: /var/backups/server-6849.zip
OR
Example 2: c:\Backups\server-6849.zip
Note: The backup files generated by the

server_conf_backup command tool are zip files.
Therefore, the server_conf_restore command will look
for a zip file extension, even if you do not specify the “.zip”
extension in your filename.
-o When copying the contents of the backup zip files into the
destination directory, the “-o” option instructs
server_conf_restore to overwrite any existing backup
files with the new ones. If you do not specify “-o” then the
server_conf_restore tool will prompt you for permission
to overwrite any existing files.
-v Verbose mode. Prints out information about the progress
and completion of the backup.
Example:
This example is for a UNIX machine with a Broker Server created on port 8849. It is
assumed that the Broker Server is running as user bin and that all the data files are located
in the Broker data directory.
server_conf_backup /var/backups/server-8849-backup-2005-05-10 –h
localhost:8849
At some point in time later a failure occurs and you need to restore the Broker Server
needs.
2 Login as root.
cd /var/opt/webmethods/awbrokers65/server8849
3 Make a copy of the Broker Server’s current configuration and run-time data file.
cp *.qs* /tmp/server-backup

4 Remove the Broker Server’s run-time data files by removing the files ending with
“.qs.stor” and “.qs.log”:
rm *.qs.stor *.qs.log
5 Run the server_conf_restore command line tool to restore the Broker Server's
configuration data storage from a backup.
server_conf_restore var/backups/server-8849-backup-2005-05-10 –v
6 Change the permissions on the restored files.

chown bin *.qs*
chgrp bin *.qs*
7 Restart the Broker Server.

server_config start –h localhost:8849
8 Run server_conf_restore for each Broker Server you need to restore.
server_config add
The add subcommand has two uses:
To control which Broker Server executable to use. By specifying the executable, you
can run a Broker Server other than the default one.
To add a Broker Server by using or copying the configuration of an existing Broker
Server. By specifying an existing configuration file, you can propagate Broker Server
configurations among multiple platforms, add a previously configured Broker Server
to an active configuration, or quickly upgrade an existing Broker Server deployment
to a new release of webMethods Broker.
Syntax
server_config add data_dir <-e executable -k license_key |
-m config_file> [-k license_key] [-p port] [-S]
Arguments
data_dir The path to the data directory for the Broker Server you are
adding. If the directory does not already exist, the program
creates it.
Use double quotes if there is spacing in the data directory path.
-e executable The path to the awbroker executable file. This option allows you
to run a Broker Server using an earlier release of webMethods
Broker. The -k option (license key) is required. Do not use in
combination with the -m option.

server_config create
-m config_file The path to the awbroker.cfg file to be used for the Broker Server
to be added. A copy of the configuration file is placed in data_dir.
This option allows you to copy an existing Broker Server
configuration. Do not use in combination with the -e option.
-p port The port number to be used for the Broker Server to be added.
Needed if the default port 6849 is in use by another Broker Server.
This port number overrides any existing port number.
-k license_key The Broker Server run-time license key. This license key overrides
any existing license key.
-S Silent operation. No output is shown except for warnings and
error messages.
Example 1
The following example adds a new Broker Server (placing a configuration file in the new
server directory) by copying the existing configuration file in the server2 directory, and
specifying a new port number.
server_config.exe add “C:\Program
Files\webmethods6\Broker\data\awbrokers65\newserver” -m “C:\Program
Files\webmethods6\Broker\data\awbrokers65\server2” -p 6830
Example 2
The following example adds an existing Broker Server to the active configuration. The
configuration file already exists in the old server directory.
server_config.exe add “C:\Program
Files\webmethods6\Broker\data\awbrokers65\oldserver”
It is possible to run multiple Broker Servers on the same host, as long as the port numbers
used by both Broker Servers do not conflict with each other. server_config create
creates the Broker Server configuration file awbroker.cfg and the data files that will be
used by individual Brokers running on the Broker Server (described in “Backing Up and
Restoring System Configuration Data Storage” on page 85). The command places the
awbroker.cfg file and the data files in the Broker Server data directory.
The server_config create command also lets you create either separate storage
sessions for the configuration (metadata) and run-time data or a combined storage session
for both types of data.
Using separate storage sessions minimizes the risk of corruption that might occur
with a combined storage location. In addition, you can use the webMethods Broker

6.5 online backup tool to back up configuration data without having to shut down
your Broker Server. This means you can continue to send and receive messages while
backing up your configuration data. For more information about the online backup
tool, see the “Backing Up and Restoring System Configuration Data Storage” on
page 85.
If you do not need to use the online backup tool, you can continue to use a combined
storage session that might save you a small amount of disk space. For more
information, see “Backing Up and Restoring System Configuration Using ADL” on
page 82.
When you create a Broker Server, you can select the storage session configuration type.
Once you do so, however, you cannot change it afterwards.
Important! At this time, it is not possible to convert either from a combined storage session
to separate storage sessions or vice-versa.
Creating Separate Storage Sessions

Create separate storage sessions for configuration and run-time data if you want to use
the webMethods Broker 6.5 online backup tool. You must type this entire command on a
single line. By default, server_config create creates separate storage sessions.
Syntax
server_config create data_dir -k license_key
[-d description] [-p port] [-nostart] [-S]
[-session_config qs [-qs_log_file filename file_size]
[-qs_storage_file filename file_size [reserved_size]]
[-session_data qs [-qs_log_file filename file_size]
Arguments
data_dir Fully qualified path to the data directory for the Broker
Server being created. If the path includes spaces, enclose
the spacing in double quotation marks.
If the directory does not already exist, the program
creates it. The directory cannot contain a copy of the
awbroker.cfg file.
-k license_key Broker Server run-time license key.

[-d description] One-line description that describes the Broker Server you
are creating. If the text string includes spaces, enclose the
in double quotation marks.
The description will appear in the Broker Administrator
main window.
[-p port] The Broker Server port number. By default, the Broker
Server uses port 6849. If another Broker Server is using
that port, you must use this argument to identify the port
the Broker Server you are creating is to use.
[-nostart] By default, the command starts the Broker Server auto-
matically after it creates it. If you want to start the Broker
Server manually later instead, use this argument to pre-
vent the command from starting the Broker Server.
[-S] By default, the command writes error messages to stderr
and information messages to stdout. If you want to write
error messages to stdout and suppress information mes-
sages instead, use this argument.
[-session_config qs] Creates the configuration (metadata) storage session with
the following defaults:
Log file named BrokerConfig.qs.log with a maximum
size of 32M
Storage file named BrokerConfig.qs.stor with a
maximum size of 512M and an initial (reserved) size
of 64M
Note: When you create a Broker Server, you can select the
session configuration type. Once you do so, however,
you cannot change it afterwards.
At this time, it is not possible to convert either from a
combined storage session to separated storage sessions
(config and run-time data) or vice-versa.

[-session_data qs] Creates the run-time storage session with the following
files:
Log file named BrokerData.qs.log with a maximum
size of 32M.
Storage file named BrokerData.qs.stor with a
of 64M.
[-qs_log_file filename identifies the fully qualified path to the file in
filename file_size] which you want Broker Server to store log data.
file_size specifies the size of the log file. Follow the
amount with K (kilobytes), M (megabytes), or G
(gigabytes).
Depending on which type of storage session you specify,
the log file name changes. The default is:
For -session_config:
-qs_log_file data_dir/BrokerConfig.qs.log 32M
For -session_data:
-qs_log_file data_dir/BrokerData.qs.log 32M
where the default log size is 32 MB. Anticipate a small

delay in operation while the command initializes the files.
You can remove or replace log files and you can increase
or decrease their size.

[-qs_storage_file filename identifies the fully qualified path to the storage
filename file_size file. Each storage session can have multiple storage files.
[reserved_size]
file_size specifies the maximum space allowed for the
storage file based on the storage session type specified,
e.g., session_config or session_data. Change the
value of file_size to increase the storage size.
reserved_size specifies the amount of storage that should
be initially allocated. This value cannot be less than 16
MB. Once you set the reserved_size, you cannot decrease
its size.
Follow the size amounts with K (kilobytes), M
(megabytes), or G (gigabytes).
the storage file name changes. The default is.
-qs_storage_file data_dir/BrokerConfig.qs.stor
512M 64M
For -session_data:
-qs_storage_file data_dir/BrokerData.qs.stor
512M 64M
For use_combined_storage:
-qs_storage_file data_dir/Broker.qs.stor
512M 64M
where the default sizes are: a maximum storage size of

512 MB and a reserved storage size of 64 MB. Anticipate a
small delay in operation while the command initializes the
files.
You cannot remove storage files or decrease their size.
Example 1
The following example creates a new Broker Server files using port number 6840. The
required license key is abbreviated for brevity. This example uses the default storage
parameters and creates a Broker Server with separate storage files.
server_config create “C:\Program
Files\webMethods6\Broker\data\awbrokers65\server2” -k BKR-XXXX -p 6840

Example 2
The following example creates a new Broker Server using port number 7849. The required
license key is abbreviated for brevity. This example creates a Broker Server with separate
storage files:
32 megabyte log file and 2 gigabyte storage file for configuration data and
1 gigabyte log file and 30 gigabyte data file for run-time data; 5 gigabytes of the 30
gigabytes are allocated when the file is created.
server_config create “C:\Brokers\Server-7849 -k BKR-XXXX” -p 7849 \
-desc “Broker Server for manufacturing” \
-session_config qs \
-qs_log_file “C:\Brokers\Server-7849\BrokerConfig.qs.log” 32M \
-qs_storage_file “C:\Brokers\Server-7849\BrokerConfig.qs.stor” 2G \
-session_data qs \
-qs_log_file “C:\Brokers\Server-7849\BrokerData.qs.log” 1G \
-qs_storage_file “C:\Brokers\Server-7849\BrokerData.qs.stor” 30G 5G
Creating a Combined Storage Session

To create a combined storage session, you must type this entire command on a single line.
By default, server_config create creates separate storage sessions.
Syntax
server_config create data_dir -k license_key
[-d description] [-p port] [-nostart] [-S]
[use_combined_storage flag]
Arguments
data_dir Fully qualified path to the data directory for the Broker
Server being created. If the path includes spaces, enclose
the spacing in double quotation marks.
If the directory does not already exist, the program
creates it. The directory cannot contain a copy of the
awbroker.cfg file.
-k license_key Broker Server run-time license key.

[-d description] One-line description that describes the Broker Server you
are creating. If the text string includes spaces, enclose the
in double quotation marks.
The description will appear in the Broker Administrator
main window.
[-p port] The Broker Server port number. By default, the Broker
Server uses port 6849. If another Broker Server is using
that port, you must use this argument to identify the port
the Broker Server you are creating is to use.
[-nostart] By default, the command starts the Broker Server auto-
matically after it creates it. If you want to start the Broker
Server manually later instead, use this argument to pre-
vent the command from starting the Broker Server.
[-S] By default, the command writes error messages to stderr
and information messages to stdout. If you want to write
error messages to stdout and suppress information mes-
sages instead, use this argument.
[-session_config qs] Creates the combined storage session with the following
defaults:
size of 32M
of 64M

(gigabytes).
The default is.
-qs_log_file data_dir/Broker.qs.log 32M

delay in operation while the command initializes the
files.
[reserved_size]
its size.
The default is.
512M 64M
small delay in operation while the command initializes
the files.
-use_combined_storage Flag to create combined storage sessions for
configuration and run-time data.

server_config delete
Example 1
license key is abbreviated for brevity. The example uses the default storage parameters
and creates a Broker Server with a combined storage file.
server_config.exe create “C:\Program
Files\webmethods6\Broker\data\awbrokers65\server2 -k BKR-XXXX” -p 6840
-use_combined_storage
Example 2
license key is abbreviated for brevity. This example creates a Broker Server with a
combined storage file: a 1 gigabyte log file and 30 gigabyte data file for all data; 5
gigabytes of the 30 gigabytes are allocated when the file is created.
server_config create “C:\Brokers\Server-7849” -k BKR-XXXX -p 7849 \
-desc “Broker Server for manufacturing” \
-use_combined_storage \
-session_config qs \
-qs_log_file “C:\Brokers\Server-7849\Broker.qs.log” 1G \
-qs_storage_file “C:\Brokers\Server-7849\Broker.qs.stor” 30G 5G
server_config delete
The delete subcommand removes the Broker Server configuration file, all of the data
files associated with the Broker Server (and any other file(s) residing in the directory), and
the data directory. When you execute the command to delete a Broker Server, you are
presented with configuration information for the Broker Server and prompted to
continue. Before you delete a Broker Server, make sure the Broker Server is not running.
Syntax
server_config delete data_dir [-f] [-S]
Arguments
Example
The following example deletes a Broker Server.
server_config.exe delete “C:\Program
Files\webmethods6\Broker\data\awbrokers65\server2”

server_config help
Lists all the available server_config subcommands and provides a brief explanation of
each. If you need detailed information about a subcommand, use server_config help
followed by the subcommand.
Syntax
server_config help
Example
The following example returns a description, including variables and notes, for the add
subcommand:
server_config help add
server_config list
The list subcommand contacts the Broker Server Monitor and provides a list of known
Broker Servers, their configurations, and current status. If the program cannot contact the
Broker Server Monitor, it provides a list of the configurations of known Broker Servers
from the Broker Server configuration file. This is the only subcommand to server_config
that you can use with a host other than the local host.
Syntax
server_config list [-h host]
Arguments
-h host Lists Broker Servers running on the specified Broker Server Host.
Example
The following lists the running Broker Servers on the host atlas.
server_config list -h atlas

server_config remove
server_config remove
The remove subcommand removes the Broker Server from the configuration file, but
does not remove the data directory. Therefore you can add the Broker Server back to the
configuration file at another time. When you execute the command to remove a Broker
Server, you are presented with configuration information for the Broker Server and
prompted to continue. Before you remove the Broker Server, make sure the Broker Server
is not running.
Syntax
server_config remove [-f] [-S]
Example
The following example removes a Broker Server.
server_config.exe remove “C:\Program
Files\webmethods6\Broker\data\awbrokers65\server2”
server_config start
The server_config start command starts the Broker Server.
Syntax
server_config start -h host:port
Arguments
Arguments Description
-h Displays a usage message.
host:port The name of the Broker Server to be started. If you omit the Broker
Server name, the Server on the local host is assumed. If you omit
the port number, the default port 6849 is assumed.
See also: “broker_stop and broker_start” on page 262.
server_config stop
The stop subcommand stops all Brokers running on the Server, halts all document
delivery, and disconnects all clients.
To stop a Broker Server, use this command syntax:
server_config stop -h host:port

Arguments
host:port The name of the Broker Server to be stopped. If you omit the
Broker Server name, the Server on the local host is assumed. If you
omit the port number, the default port 6849 is assumed.
See also: “broker_stop and broker_start” on page 262.
server_config storage
The server_config storage subcommand configures storage sessions for a specified
Broker Server.
For a combined storage configuration, upon installation of a Broker Server, the user will
have created two separate data files: a log file, which data is first written before being
used in the second file, the storage file.
For a separate storage configuration, upon installation of a Broker Server, the user will
have created four separate data files: two log files and two storage files. One set of the
log and storage files is used for storing Broker configuration data and the other set is
used for Broker run-time data.
You can use server_config storage to change the storage file sizes.
File type Default file size Maximum file size

log file 32 MB 1 GB
storage file 512 MB 32 GB
In addition to the storage file created upon installation, you can add up to 61 additional
storage files—each with a maximum size of 32GB—to a Broker Server.
Note: You must stop the Broker Server before configuring additional storage files.

You must type this entire command on a single line.
Syntax
[-session_data qs [-qs_log_file filename file_size]
Arguments
[-session_config qs] The configuration (metadata) storage session with the
following defaults:
size of 32M
of 64M
[-session_data qs] Creates the run-time storage session with the following
files:
Log file named BrokerData.qs.log with a maximum
size of 32M.
Storage file named BrokerData.qs.stor with a
of 64M.

(gigabytes).
the log file name changes. The default is:
-qs_log_file data_dir/BrokerConfig.qs.log 32M
For -session_data:
-qs_log_file data_dir/BrokerData.qs.log 32M

delay in operation while the command initializes the files.

[reserved_size]
its size.
the storage file name changes. The default is.
-qs_storage_file data_dir/BrokerConfig.qs.stor
512M 64M
For -session_data:
-qs_storage_file data_dir/BrokerData.qs.stor
512M 64M
For use_combined_storage:
512M 64M

small delay in operation while the command initializes the
files.
Example
The following example creates an additional runtime storage file for a Broker Server:
"C:\ProgramFiles\webmethods6\Broker\data\awbrokers65\default" \
-session_data qs \
-qs_storage_file “:\Brokers\Server-7849\BrokerData.qs.stor 30G 5G

server_config update
You can update the following configuration information for an existing Broker Server
using the server_config update subcommand:
run-time license key
Port number of the server. .
Tip! On Windows, the port number is part of the service name. Hence, if you change the
port number, the program attempts to change the service name, an action that may not
succeed. To update a port number on Windows, another strategy is to use the create
subcommand to create a new Broker Server, copy the data files from the old data
directory (not including the awbroker.cfg file), and delete the old Broker Server using the
delete subcommand.
Syntax
server_config update data_dir [-k license_key] [-d description]
[-p port] [-S]
For the changes to take effect, you must restart the Broker Server. To change the port
number. You must stop the Broker Server before using the server_config program.
Arguments
data_dir The path to the data directory for the Broker Server you are
updating.
Use double quotes if there is spacing in the data directory path.
-k license_key The new run-time license key.
-d description A new description of the Broker Server. This optional description
appears in the Broker Administrator main window. If the text
string includes spaces, enclose it in quotation marks.
-p port A new port number to be used by the Broker. Stop the Broker
before you attempt to change the port number.
-S Silent operation. No output is shown except for warnings and
error messages.

broker_buildall
Example
The following example updates the configuration of a Broker to use a new run-time
license key. The required license key is abbreviated here.
server_config.exe update “C:\Program
Files\webmethods6\Broker\data\awbrokers65\server2” -k BKR-XXXX
broker_buildall
Use the broker_buildall command line utility to compile all pre-webMethods 6.x
intelligent integration components and scripted operations from a Broker.
When you run the broker_buildall command line utility, it compiles all components on
the Broker that have the “Need to compile” status. If an error is encountered while
compiling, broker_buildall writes a message to the event log and continues with the
next component. You can recompile if necessary.
Syntax
broker_buildall [-force] [-output] [-h] [-?] [--] [broker@]server[:port] [-
idhelp] [id_options]
Arguments
-? Displays usage help for Java command line options
-force Causes the tool to bypass error checking. Forces a recompile for
every Scripted Operation and Intelligent Integration Component
regardless of their state.
-output The command outputs standard output name of component being
compiled.
-- Allows the Broker name to start with the character -.
[broker@]server[: The name of the Broker Server (and optionally, the Broker and the
port] port number) on which to load the Broker information. If you omit
the Broker name, the default Broker is assumed. If you omit the
Broker Server, only syntax checking is performed on the file.
-idhelp Displays a usage message for the ID options.

[id_options] Provide identification needed for administrative access to Brokers
or webMethods Brokers if they are protected by Access Control
Lists (ACLs).
Using ACLs, it is possible to limit administrative access to Brokers
or webMethods Brokers. To be granted access, you must provide a
distinguished name that matches the ACL for the Broker or
webMethods Broker, as described in “Access Control Lists” on
page 167. To gain administrative access, use the following ID
options with the broker_buildall command:
-certfile Name of the certificate file to be used for this connection.
filename
-password Password for the certificate file. You will be prompted for the
password password if you omit it from the command.
-dn name The distinguished name used to provide the Identity for this
command. Optional if there is only one distinguished name in the
certificate file.
-noencrypt Do not use encryption for the connection. By default, every
connection using a certificate is encrypted.
broker_create
If you want to work from the command line, rather than from Broker Administrator, you
can use the broker_create command to create a Broker.
Syntax
broker_create -h [[--]broker[@server[:port]] [-default]
[-description text] [-createterr territory]
[-jointerr broker[@server[:port]]] [-idhelp] [id_options]
Arguments
-- Allows the Broker name to start with the
character -.
broker[@server The name to be assigned to the Broker. Broker Server and port
[:port]] number are optional if the Broker Server is on the local host.
-default Makes the Broker the default Broker.

broker_create
-description A one-line description of the Broker, to be displayed in Broker
text Administrator main window.
-createterr Creates a new territory and makes the new Broker the first member.
territory
-jointerr Makes the new Broker a member of the territory that the specified
broker Broker is a member of.
[@server[:port]]
-idhelp Displays a usage message for the ID options listed below.
or Broker Servers if they are protected by ACLs. See the following
list of ID options.
or Broker Servers. To be granted access, you must provide a
distinguished name that matches the ACL for the Broker or Broker
Server, as described in “Access Control Lists” on page 167.
To gain administrative access, use the following ID options with the
broker_create command:
filename
certificate file.

broker_delete
If you want to work from the command line, rather than from Broker Administrator, you
can use the broker_delete command to delete a Broker. The named Broker leaves its
territory, if it belongs to one. All client queues on the Broker are lost, all client queues are
disconnected, and the Broker, all of its document types, and client groups are deleted
permanently. By default, you are prompted to confirm this command.
syntax
broker_delete [-h] [-y] [[--] broker@server[:port]] [-idhelp] [id_options]
Arguments
-y Implied “yes.” If this option is included, the command does not
prompt for confirmation before deleting the Broker.
character -.
broker@server The name of the Broker to be deleted and the Broker Server on
[:port] which it resides. If you do not specify the port number, the default
port is assumed.
or webMethods Brokers if they are protected by ACLs.
options with the broker_delete command:
filename
certificate file.

broker_load
broker_load
Use the broker_load program, from the command line, to import Broker data from a file
to a Broker:
Note: If the import file contains a new SSL configuration, you may need stop and restart
the Broker Server for the configuration to take effect. In such cases, the broker_load
program prompts for whether or not you want to stop and restart the Broker Server at
that time. Also, if the import file does not contain the password for the certificate file, you
are prompted for it.
Important! The broker_load program divides large files into 2MB pieces. The pieces are
then imported sequentially to the Broker and reassembled. If an error occurs during this
process, some document types may still be loaded, that is, the file may be partially
loaded if there is an error and the Broker is left in a partially updated state.
Syntax
broker_load [-h] input_file [-force] [-merge] [-write output_file]
[[--] [broker@]server[:port]] [-idhelp] [id_options]
Arguments
input_file The file you saved the Broker configuration information to using
the broker_save command.
-force Causes the tool to bypass error checking.
-write The command writes a copy of the definitions in the input file to
output_file the specified output file using the latest revision of the export file
format. If no output file is specified, the only output is syntax
errors.
character -.
[broker@]server[: The name of the Broker Server (and optionally, the Broker and the
port] port number) on which to load the Broker information. If you omit
the Broker name, the default Broker is assumed. If you omit the
Broker Server, only syntax checking is performed on the file.

or webMethods Brokers if they are protected by Access Control
Lists (ACLs).
options with the broker_load command:
-certfile filename
Name of the certificate file to be used for this connection.

-password password
Password for the certificate file. You will be prompted for

the password if you omit it from the command.
-dn name
The distinguished name used to provide the Identity for

this command. Optional if there is only one distinguished
name in the certificate file.
-noencrypt
Do not use encryption for the connection. By default,

every connection using a certificate is encrypted.
-merge This command merges non-system document types on import. To
use -merge, the document types must have the same name.
Note: broker_load will return an error message if the two

documents have same field names but different field types.

broker_ping
broker_ping
Use the broker_ping command to send system ping documents through a Broker. If the
document passes through the Broker Server and returns to broker_ping, a positive
message is printed. By default, one document is sent. If no document returns, a negative
message is printed. The broker_ping command has the following syntax:
broker_ping [-h] [-s] [-c count] [-remote [/territory/]broker2]
[[--] [broker@]host[:port]] [-idhelp] [id_options]
The broker_ping command uses the following arguments:

-s Sends a document through the Broker Server once
every second.
-c count Specifies the number of documents that are sent
through the Broker
-remote [/territory/]broker2 Pings broker2 remotely through the Broker. See
“Pinging a Remote Broker” on page 260.
character -.
[broker@]host[:port] The name of the Broker Server (and optionally, the
Broker or port) you want to ping. If you omit the
Broker name, the default Broker is assumed.
-idhelp Displays a usage message for the ID options listed
below.
[id_options] Provide identification needed for administrative
access to Brokers or Broker Servers if they are
protected by Access Control Lists. See the following
list of ID options.
Using Access Control Lists (ACL), it is possible to limit administrative access to Brokers or
Broker Servers. To be granted access, you must provide a distinguished name that
matches the ACL for the Broker or Broker Server, as described in “Access Control Lists”
on page 167. To gain administrative access, use the following ID options with the
broker_ping command:
-certfile filename Name of the certificate file to be used for this connection.
-password password Password for the certificate file. You will be prompted for

-dn name The distinguished name used to provide the Identity for
Pinging a Remote Broker

You can use the broker_ping command-line program to ping a remote Broker in the
same territory or in a territory that is connected by a territory gateway. The ping
document passes through the local Broker to the remote Broker, allowing you to trace the
connection between Brokers. For example, assume that you want to trace the connection
between local Broker Alpha on the host atlas and remote Broker Beta in the same territory.
The command is:
broker_ping -remote Beta Alpha@atlas
To ping the Broker Gamma, which is in the territory T-2, across a territory gateway, the
command is:
broker_ping -remote /T-2/Gamma Alpha@atlas
To use broker_ping across a territory gateway, the document type Broker::Ping must be
shared across the gateway. For more information about sharing documents across
territory gateways, see “Territory Gateways” on page 142.
broker_save
Use the broker_save program from the command line to save Broker configuration
information for a specified Broker to a file.
-broker include the Brokers configuration (description,
territory, and any gateways) in the save file,
the default is to exclude it from the save file.
-server include the Servers configuration (SSL identity
and an Access Control List) in the save file,
the default is to exclude it from the save file.
-native write unicode characters using the native file format
(which results in language-dependent file that
may be easier to edit and use locally)

broker_save
Syntax
broker_save [-h] [-broker] [-server] [-native] output_file
[[--] [broker@]server[:port]] [-idhelp] [id_options]
Arguments
-broker Includes the Broker’s configuration in the save file. The
configuration information includes: description, territory, and any
gateways. The default is to exclude it from the file.
-server Includes the Broker Server’s SSL configuration and logging options
in the save file. The default is to exclude them from the file.
-native Write Unicode characters using the native file format.
-- Allows the Broker name to start with the character -.
[broker@]server The name of the Broker Server (and optionally, the Broker and port
[:port] number) from which to save the Broker information. If you omit the
Broker name, the default Broker is assumed.
[id_options] Provide identification needed for administrative access to Brokers or
webMethods Brokers if they are protected by ACLs.
Using ACLs, it is possible to limit administrative access to Brokers or
webMethods Brokers. To be granted access, you must provide a
page 167. To gain administrative access, use the following ID options
with the broker_save command:
-certfile filename
-password password
-dn name
The distinguished name used to provide the Identity for this
command. Optional if there is only one distinguished name
in the certificate file.
-noencrypt
Do not use encryption for the connection. By default, every

Note: Document types, client groups, and clients are always included in the save file.
Examples
To save a configuration file for each server and each Broker in the configuration, use:
For Broker Servers:
broker_save -server alpha.adl Alpha
broker_save -server beta.adl Beta
For Brokers:
broker_save -BrokerA.adl Broker A@Alpha
broker_save -BrokerB.adl Broker B@Alpha
broker_save -BrokerC.adl Broker C@Beta
broker_save -BrokerD.adl Broker D@Beta
The preceding examples of the broker_save command do not show a full pathname for
the ADL file and do not include (optional) SSL identification options.
broker_stop and broker_start

You can use the broker_stop and broker_start commands to stop and start the Broker
Server. The awbrokermon process must be running to use the broker_stop and
broker_start commands. These commands wait up to 20 seconds for the Broker Servers
to stop or start, and visual feedback is given when the Broker Servers take more than a
second to stop or start. For information about the awbrokermon process, see “Shutting
Down the webMethods Broker Processes” on page 264.
broker_stop
The broker_stop command stops all Brokers running on the Broker Server, halts all
document delivery, and disconnects all clients.
Syntax
broker_stop [-h] [-idhelp] [-y] [server[:port]] [id_options]
Arguments
-y Implied “yes.” If this option is included, the command does not
prompt for confirmation before stopping the Broker Server.

broker_stop and broker_start
server[:port] The name of the Broker Server you want to stop. If you omit the
Broker Server name, the Broker Server on the local host is
assumed. If you omit the port number, the default port 6849 is
assumed.
or Broker Servers if they are protected by ACLs. See the following
list of ID options.
or Broker Servers. To be granted access, you must provide a
distinguished name that matches the ACL for the Broker or Broker
Server, as described in “Access Control Lists” on page 167.
To gain administrative access, use the following ID options with
the broker_stop command:
-certfile filename

-password password

-dn name
The distinguished name used to provide the Identity for

-noencrypt
Do not use encryption for the connection. By default,

every connection using a certificate is encrypted.
broker_start
The broker_start command starts the Broker Server.
Syntax
broker_start [-h] [server[:port]]

Arguments
[server[:port] The name of the Broker Server you want to start. If you omit the
Broker Server name, the Broker Server on the local host is
assumed. If you omit the port number, the default port 6849 is
assumed.
To shut down a Broker Server (awbrokermon and awbroker processes) on Solaris, HP-UX,
and Windows platforms, use the commands described in the following sections.
Shutting Down the webMethods Broker Processes
Shutting Down the webMethods Broker Processes on Solaris
Note: On Solaris, you can only run these commands as user root or user bin. These
To stop the awbrokermon process, enter this command:

/etc/rc3.d/S45broker65 stop
To restart the webMethods Broker processes, enter this command:
/etc/rc3.d/S45broker65 start
Shutting Down the webMethods Broker Processes on HP-UX
Note: On HP-UX, you can only run these commands as user root or user bin. These
To stop the awbrokermon process, enter this command:

/sbin/rc3.d/S45broker65 stop
To restart the webMethods Broker processes, enter this command:
/sbin/rc3.d/S45broker65 start

broker_status
broker_status
The broker_status command displays statistics from the command line for a specific
Broker. The statistics displayed include Broker status, document delivery statistics, and
client statistics.
Syntax
broker_status [-h] [-idhelp] [id_options] [broker@]server[:port] ...
Arguments
[id_options] Provide identification needed for administrative access to
Brokers or webMethods Brokers if they are protected by Access
Control Lists (ACLs).
Using ACLs, it is possible to limit administrative access to
Brokers or webMethods Brokers. To be granted access, you
must provide a distinguished name that matches the ACL for
the Broker or webMethods Broker, as described in “Access
Control Lists” on page 167. To gain administrative access, use
the following ID options with the broker_status command:
filename
command. Optional if there is only one distinguished name in
the certificate file.
[broker@]server[:port] The name of the webMethods Broker (and optionally, the
Broker and port number) from which to receive status. If you
omit the Broker name, the Broker Server sends the status of all
Brokers.


APPENDIX B
Tips and Troubleshooting
Tips on Using webMethods Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
webMethods Broker Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

AP P E N DI X B Tip s an d Tr o ub le sh o o ti ng
This chapter describes some troubleshooting commands and lists common

troubleshooting tips. It also contains lists of error messages for the Broker Server.
Tips on Using webMethods Broker
Importing Large ADL Files

You can use Broker Administrator or the broker_save and broker_load command line
utilities to import large ADL files.
When using Broker Administrator to import large ADL files, keep in mind that the
transfer speed is limited to the HTTP connection speed and it may take a long time to
import the file. If you must use Broker Administrator to import a large ADL file, increase
the Session Timeout value for the Integration Server to prevent the session from timing
out. For instructions, see “Increasing the Session Timeout Value for Integration Server”
below.
For a faster transfer time, use the broker_save and broker_load command line utilities.
These tools allow you to import and export large ADL files more quickly as they do not
transfer data over an HTTP connection.
Increasing the Session Timeout Value for Integration Server
To increase the Session Timeout value
1 Open the Server Administrator by clicking Administration in the banner area of Broker
Administrator.
2 In the Settings menu of the navigation area, click Resources.
3 Click Edit Resource Settings.
4 In the Session Timeout field, increase the number of minutes you want the server to
wait before terminating a session.
For more information about the setting the Session Timeout limit, see the webMethods
Integration Server Administrator’s Guide.
Importing a Large ADL File Using the broker_load Command Line Utility
To export and import a large .adl file from a command line
1 Open a command line prompt.

2 CD to the \\webMethods6\Broker\bin directory.

3 Export Broker information to an .adl file by entering the following command:

broker_save filename.adl [broker@]server[:port]
Replace filename with the name of the output .adl file and replace broker@server:port
with the name of the Broker Server (and optionally, the Broker and port number)
from which to save the Broker information. If you omit the Broker name, the default
Broker is assumed.
Example:
broker_save LargeFile.adl hercules:7000
The file is saved in the \\webMethods6\Broker\bin directory.

For more broker_save command line options, see “broker_save” on page 260.
4 Import the .adl file by entering the following command:
broker_load -Xmx256M directory\filename.adl [broker@]server[:port]
Replace directory and filename with the location and the name of the .adl file. Replace
broker@server:port with the name of the Broker Server (and optionally, the Broker and
the port number) on which to load the Broker information. If you omit the Broker
name, the default Broker is assumed.
Example:
broker_load -Xmx256M \webMethods6\Broker\bin\LargeFile.adl atlas:6849
For more broker_load command line options, see “broker_load” on page 257.
Setting Maximum Thread Limit for HP-UX

For HP-UX 11, the default maximum number of threads per process is 64. If the number of
Brokers on a Broker Server exceeds 10, or if there are many active clients, you may need to
increase the maximum number of threads per process. Thread usage is as follows:
Each: Uses:
Broker Server 10 threads

Broker 2 to 5 threads
To change the limit on the maximum number of threads per process, use the
max_thread_proc kernel parameter in the HP-UX System Administration Manager
(SAM). For more information on SAM, see your HP-UX documentation.

Working Without a Network Connection

When a network connection is lost or interrupted on a Windows machine, Broker
Administrator cannot properly reconnect on its own. If you ever want to work without a
network connection (for example, during a software demonstration or training course), or
if you anticipate network interruptions, you can run webMethods Broker locally to avoid
reconnection errors.
To work without a network connection
1 Ensure that the webMethods Broker, the Integration Server, and Broker
Administrator are installed on the local machine. Refer to the webMethods Installation
Guide for detailed instructions.
2 On the same machine, configure a Broker Server using the name “localhost” instead
of the hostname or IP address of the machine. Creating Broker Server localhost,
allows the machine to be disconnected from the network at anytime without
generating errors.
Tip! With Broker Administrator you can create multiple instances of a single Broker
Server. For example, you can create a Broker Server instance using its actual hostname
so that it is available on the network and create another instance of the same Broker
Server using “localhost” as its hostname so that it is available offline. For more
information, see “Working with Multiple Instances of a Single Broker Server” in the
next section.
Working with Multiple Instances of a Single Broker Server

A single Broker Server can be added multiple times to the Broker Administrator Known
Servers page. webMethods recommends having only one Broker Server instance in the
Broker Administrator, although this configuration may be useful if you have a Windows
machine that will be working offline from time to time.
Important! If you have multiple instances of a single Broker Server, please note that it will
cause redundancies in the Territories List and Join Territory pages; that is, the same
territories will be listed multiple times.
Adding Multiple Instances of a Broker Server to Broker Administrator

To add a Broker Server to the Broker Server’s view, a unique, valid name for the Broker
Server must be provided. A valid name can be any one of the following:
Actual name of the host where the Broker Server is running
IP address of the Broker Server

“localhost” or 127.0.0.1 (use only if the machine will be working offline.)

Add multiple instances of a single Broker Server to the Known Servers page by using a
different name for each instance. For example, if the name of the first Broker Server
instance is the actual name of the host where the Broker Server is running, the second
instance can be added using localhost as the name.
To add multiple instances of a Broker Server to the Known Servers page
1 Follow the steps in “Adding a Broker Server to Broker Administrator” on page 45 to

add the first instance of the Broker Server.
2 Repeat the steps 1-3, to create the second Broker Server instance.
3 In the Hostname field, type a different name for the Broker Server. Choose from the list
of valid names above.
4 A confirmation message will appear, click Yes to add the Broker Server.
Scaling the webMethods Broker System

This section answers some common questions regarding the scalability of a webMethods
Broker system.
What is the maximum number of Brokers per webMethods Broker Server?

There is no fixed limit to the number of Brokers that can run on a single Broker Server.
The Brokers, however, share the storage and memory resources available to the Broker
Server.
Several factors determine the number of Brokers a given Broker Server can support,
including the following:
Storage types The Broker Server’s Persistent and Guaranteed storage files
each have a fixed maximum size. See “Client Queue Storage
Types” on page 95 and “Maximum Storage File Size” on
page 96.
Client Group life A document with an explicit destroy life cycle remains in a
cycle client queue until the receiving client pulls it from the queue.
See “Life Cycle Properties” on page 95.
Memory resources Factors such as the amount of physical memory and swap
space can determine how quickly documents pass through a
Broker. For information tuning your webMethods Broker
system for performance, see the webMethods Installation Guide
Thread limits on For HP-UX systems, see “Setting Maximum Thread Limit for
HP-UX HP-UX” on page 269.

A Broker Server might easily support over 30 Brokers if each Broker handles light traffic.
A few Brokers, each handling a high volume of large documents, may tax the Broker
Server’s capacity. For information about monitoring Broker Server usage, see “Monitoring
webMethods Broker Server Usage” on page 48.
What is the maximum number of Brokers per territory?

There is no fixed limit to the number of Brokers that can be members of the same territory.
Each Broker, however, has a network connection to every other Broker in that territory. If
all Brokers are on the same Broker Server, the number of Brokers in a territory is limited
by the number of UNIX file descriptors (or file handles on Windows) available. The
maximum number of UNIX file descriptors per Broker Server is 8,000; the maximum
number of Windows file handles is over 3,000.
The number of file descriptors required for a territory is (N*N)-N, where N is the number
of members. If there are 30 Brokers in a territory, the number of file descriptors is 870. If
the members of this territory reside on two different Broker Servers, the number of file
descriptors per server drops to 435.
What is the maximum number of Territories per webMethods Broker Server?

There is no fixed limit to the number of territories that can exist on a Broker Server.
Territories do not have a server-level presence. Each Broker on a Broker Server can be a
member of a different territory. Put another way, you can have as many territories on a
Broker Server as the number of Brokers on that server, but no more.
What is the maximum number of Broker clients per Broker?

The maximum number of clients per Broker is limited by the number of file descriptors
available to the Broker Server. Each client connection requires one file descriptor. Clients
in the same process share a connection by default (or each client can have its own
connection), so it is possible to have more clients than there are client file descriptors. In
addition, a client that is not actively connected does not require a file descriptor.
As a rule of thumb, to determine the maximum number of Broker clients for a Broker
Server, count the number of simultaneous client connections you anticipate for all Brokers
on that server; each connection requires a file descriptor. Add this number to the number
of file descriptors required for each territory member on the same Broker Server
(described in the question about the maximum number of Brokers per territory on
page 272). This total cannot exceed the total number of file descriptors available to a
Broker Server.
In practice, the useful maximum is likely to be less than the file descriptor limit. The
document load on the Broker from local clients and remote Brokers effectively limits the
number of active clients. The maximum document load a Broker can handle depends on
several factors: Document storage type, Broker Server hardware, and network capacity.

webMethods Broker Error Messages
webMethods Broker Error Messages

For more information about Broker Server error messages, refer to the webMethods Error
Message Reference.
To view messages on Solaris, look at the log files:
/var/log/broker.alert and/var/log/broker.info.
To view messages on HP-UX, look at the log files: /var/adm/syslog/broker.alert and

/var/adm/syslog/broker.info.
To view messages on Windows, use the Document Viewer and select File, Application.


Glossary
Access Control List A list of SSL certificates that define those entities which
(ACL) may access a Broker or create a client within a particular
client group.
ActiveWorks A file format that allows you to define the characteristics
Definition Language of any webMethods Broker object, such as a Broker,
(ADL) Broker Server, client group, client, or a document type.
adapter A program that connects resources to documents.
Adapters translate information between the format
required by the resource and the common document
format. Adapters are hosted by the Integration Server.
ANSI string A string of 8-bit, ISO-Latin-1 characters. See also, UTF-8.
authentication The process of identifying the sender of the data so other
people cannot pretend to be you or pretend to be the
server you are accessing. The encryption is done
through secure sockets.
AWT Abstract Windowing Toolkit, the GUI toolkit that is
included with the Java Development Kit.
Broker A part of the Broker Server process, providing services
such as receiving, queuing, and delivering documents.
One or more Brokers can exist on a Broker Server. Each
Broker can have any number of document types, client
groups, and clients associated with it; they also share
process and storage space with other Brokers. Brokers
can be added to or leave territories.
See also, territory, territory gateway, and remote Broker.

Broker client A handle created and used by client programs that
represents a connection to a particular Broker and has a
client state. Client programs may use one or more
Broker clients.
Broker Server See webMethods Broker Server.
callback A function registered by a client program to be invoked
whenever a particular document type arrives. For
interactive applications, callbacks make receiving a
webMethods Broker document just like receiving a user
input document from the window system.
certificate A certificate contains a name, public key, private key,
and information about the issuer of the certificate. See
also public key encryption.
certificate file The storage location for one or more certificates. A
certificate file can store certificates, trusted roots, and
uncertified key-pairs. An uncertified key pair is one that
has not yet been certified by the Certification Authority.
See also, trusted root.
certificate manager A command line tool named awcertmgr that creates and
manages certificate files. The certificate manager can
add, remove, and browse X.509 compliant digital
certificates.
See also, certificate file.
Certification Authority An entity that issues certificates, usually associated with
an Authentication Server. You can check the validity of
an issued certificate by checking it against the
appropriate Authentication Server.
CLASSPATH The environment variable that tells the Java compiler
where to look for the classes it needs. -classpath is an
option to the Java interpreter and the Java compiler that
tells them (while compiling or running) where to look
for a class. -classpath overrides CLASSPATH.
client connection type A client attribute that specifies how long the Broker
keeps information about a client’s existence. Also known
as the client life cycle.
A destroy on disconnect client exists for the duration of
the connection that created the client.
An explicit destroy multi-connection client exists until it
is explicitly deleted.

client group A set of properties to be applied to specific Broker
clients. Client groups provide an access control system
for the Broker by defining:
The certificates that can access the Broker.
The document types to which the clients may
subscribe.
The document types the clients may publish.
Client connection and document queue storage type

for the clients.
client program Any program or process that creates and uses one or
more Broker clients.
client queue A list of documents stored in the Broker that matched a
client’s subscription. Client queues can support two
kinds of storage:
volatile
guaranteed (or persistent)

The client queue type is stored in the client group. See
also, storage type.
client state Information about a client that is maintained by the
Broker, including:
a client ID
an application name
a client group
a subscription list
a queue of documents not yet retrieved

client storage type See storage type.
commit A way of ending a transaction that instructs the adapter,
or adapters, to process the documents received for the
transaction.
control container An ActiveX-enabled application or development
environment that supports programmatic access to
ActiveX controls.
data field A document field that holds data defined for and used
by Broker clients. The type and number of data fields are
defined by the document type.

dbAdapter An adapter that is used to connect a relational database
to the Broker. Every dbAdapter subscribes to request
document types and publishes a collection of documents
called reply or notification documents.
deliver To transmit a document to the Broker for use by a
specific client program. See also, publish.
destroy on disconnect If this client life cycle is specified, the Broker will destroy
client state information whenever the connection
between the client and the Broker is terminated. The
client state information is destroyed whether the
disconnection is intentional or not.
See also, explicit destroy and life cycle.
distinguished name A certificate needs a distinguished name to identify the
issuer of the certificate. Distinguished names consist of
one or more of the following components:
CN, OU, O, L, ST, C
where CN is the common name, OU the organizational
unit, O the organization, L the locality, ST the state or
province, and C the country where the certificate was
issued. For example, <CN=John Smith, OU=Engineering,
O=webMethods, L=Sunnyvale, ST=CA, C=USA>.
document A generic message exchanged by resources; a common
unit of information with a standard format; a medium of
exchange. The generic nature of documents makes
possible universal tools that operate on all kinds of
documents. a webMethods Broker document commonly
corresponds to a business process document, such as
processing a purchase order.
A document is an instance of a document type. A
document contains:
its type (see document type)
a body, which contains data fields with values
an envelope, which contains envelope fields (see

document envelope)

document envelope A document part that holds information about the
document and its transit. Envelope fields are part of
documents of all types; for example, one envelope field
contains the client ID of the document publisher. Certain
document fields can be set by a client program before it
publishes the document, and certain fields are
automatically set by the Broker as it processes the
document.
document folder A group of document types that are related in some
arbitrary way (see document type). Document folders are
stored in the Broker.
S A field in the document envelope. The dbAdapter copies
this tag into any result document that it delivers. Client
applications can use the document tag to match received
reply documents with request documents that they
published.
document type A template or structure (analogous to a class in C++) for
documents. document types define the form of
documents, typically including the data fields to be
carried by the documents.
A document type is your definition of what type of
information documents are to carry. Each document
type has:
a name, which must be unique
a storage type
a field definition, describing the names of fields

within the document and the type of each field
membership in a specific document folder.
The definition of each publishable document type must
be saved in the Broker.
DSA Digital Signature Algorithm (DSA) is part of the Digital
Signature Standard (DSS), selected to be the digital
authentication standard of the U.S. Government. DSA is
intended for authentication only.

encryption The scrambling of data so that it can only be un-
scrambled by an authorized recipient. Encryption
strength is usually stated in bits. webMethods Broker
uses 128-bit encryption for domestic use and 40-bit
encryption for export use. For export purposes, only 40-
bit or weaker encryption is permissible.
See also, public key encryption.
explicit destroy If this client life cycle is specified, the client state can
only be destroyed by a webMethods Broker
administrator or by your application calling the
DestroyClient method. The client state information
persist whether the disconnection is intentional or not.
See also, destroy on disconnect and life cycle.
filtering The process of limiting acceptable documents, based on
their contents. A subscription to a document type can
contain a filter that accepts certain documents of the
given type and screens out others. The Broker examines
each document of the specified document type to see
whether it matches the filter. A subscription’s filter
selects a subset of the documents, such as invoices
whose amounts are greater than $50,000.
firewall A network gateway host that uses special procedures to
protect the hosts on a local network from unauthorized
access. By default the following port numbers are used:
For non-SSL, the Broker Server requires you to open
port 6849 on your firewall.
For SSL connections with no client certificate, port
6848 is used.
For SSL connections with a client certificate, port
6847 is used.
You can open all or just some of the above ports in your
firewall depending on what capabilities you want to
allow.
frame A kind of window that can have a menu bar. A frame
cannot be inside another window.
gateway Broker One of a pair of Brokers that share a connection across a
territory gateway. Each Broker in a territory gateway is
configured and maintained independently.
See also territory gateway.
guaranteed storage See storage type.

Java client classes The Java client library that is part of the webMethods
Broker API: Java Edition.
life cycle The amount of time the Broker will maintain client state
information about a group member. See also, client state.
There are two types of client life cycles: destroy on
disconnect and explicit destroy.
load balancing Shared client state (shared queues) allows parallel
processing to occur, thus improving performance. Load
balancing allows several adapters to handle documents
in parallel on a first-come, first-serve basis.
panel A kind of window that does not have a menu bar or
scroll bars. One or more panels can be inside other
windows.
persistent storage See storage type.
public key encryption An encryption technique that assigns each user two
keys:
a public key and
a private key.
Your public key can be freely distributed, while your
private key is kept secret. Other users may encrypt
messages they send to you using your public key and
only the holder of your private key, you, will be able to
decrypt the message. A user’s private key cannot be
derived from their public key. See also, encryption
publish To transmit a document to a Broker for use by
subscribers. An application publishes a document by
creating a document data structure or object (depending
on the application language) and then invoking its
adapter’s publishing operation. Adding and deleting
publishers has no impact on subscribers. See also, deliver.
RDBMS Relational database management system, such as
ORACLE, SYBASE, or INFORMIX.
remote Broker Another Broker in the same territory or in a territory that
is accessible through a territory gateway. From the
standpoint of a particular Broker, all other Brokers in the
territory are remote.
reply document The result of a request for data. If a request document
returns any results, these results are delivered to the
client as a reply document.

request document A document that requests something, typically
information from a database. Request documents are
published by Broker clients and subscribed to by
dbAdapters or by user-written adapters.
resource A producer or consumer of corporate information, such
as a database or an application.
rollback A way of ending a transaction that instructs the adapter,
or adapters, to discard all documents received for the
transaction.
RSA A public-key cryptosystem for the encryption and
authentication of data. webMethods Broker uses the
RSA standard. See also, public key encryptionn.
savepoint A way of marking a transaction that instructs the
adapter, or adapters, to process all documents received
so far without closing the transaction.
search record One of two records in a data source. Each field in the
search record corresponds to a field in the defined
document type. Lookup requests use the search record
to set field values in the lookup document.
secure sockets A socket is a way of sending information over a network
between two programs. Secure sockets make this
communication safe. Data is encrypted so only people
who the data is meant for can read it. See also, encryption.
shared state The process of distributing the processing of documents
to multiple client programs, possibly executing on
different hosts. This provides a very basic form of load
balancing.
SSL Secure Sockets Layer standard. See secure sockets.
storage type A document attribute that determines how each
document is stored in the Broker:
Volatile storage is memory-based; it is fast but
vulnerable to power and other failures. This is used
for documents that have a short life or are not
important.
Guaranteed storage uses a robust two-phase commit
process to store documents on disk. It is extremely
reliable, but is slow.
subgroup A child of a group.

subscription To register acceptance of a document type. A
subscription lasts until cancelled or until the client
program that subscribed is destroyed.
territory A set of Brokers that share information about their
document type definitions and client groups. Brokers
within the same territory have knowledge of one
another’s document type definitions and client groups.
Documents can travel from clients on one Broker to
clients on another Broker in the same territory.
territory gateway A connection between two Brokers in different
territories. The gateway must be configured to share
document type definitions, allowing the transfer of
documents between them. There can be only one
gateway between any two territories.
transaction A grouping of multiple documents as a single unit of
work that is to be treated atomically by the adapter, or
adapters, that are processing those documents. A
transaction is started with the publication of an
Adapter::beginTransaction document and
terminated with the publication of an
Adapter::endTransaction document.
trigger A function that monitors specific information (one or
more columns) in a database. When the value of a
monitored column changes, the trigger duplicates the
affected database record in a buffer.
Periodically, the dbAdapter translates these records into
notification documents and publishes the documents.
Subscribers can then be notified of changes to the
database, almost as they happen.
Triggers are also used to provide notification if records
are inserted into, updated, or deleted from a table.
trusted root A special certificate issued by a well-known and trusted
Certification Authority. Trusted roots are used to
validate the authenticity of certificates received by a
client or server application.
UTF-8 Unicode Transform Function 8. A formatting standard
that allows 16-bit Unicode characters to be represented
as a sequence of up to four 8-bit, ISO-Latin-1 characters.

versioning The process of extending a document type definition so that
earlier versions are not made obsolete. This allows
several versions of a document type, along with the
applications that use those versions, to exist
concurrently and indefinitely.
Each version number represents a change, such as the
addition of new fields, the removal of old fields, a
change in the name or type of a field, or a change in the
semantics of a document type.
volatile storage See storage type.
webMethods Broker webMethods Broker integrates every information
resource allowing access across corporate intranets or
the Internet.
webMethods Broker The core product of the webMethods Broker
Server communication system that runs Brokers. Broker
Servers are the delivery and administration hubs of
document-based computing. Broker Servers can have
multiple Brokers that share the same process and storage
space.
webMethods Broker The computer on which a single Broker Server or
Server Host multiple Broker Servers are installed and run.
webMethods A webMethods Enterprise adapter with its resource.
Enterprise resource

Index
A rollback 282
Abstract Windowing Toolkit (AWT), definition 275 savepoint 282
access control setting up Broker Server 23
access labels 195 SSL configuration 171
list, See ACL subscription filter strings 111
security 195 transaction 283
Access Control List, See ACL Adapters view 29
access label 195 Add Known Broker Server option 45
ALA communication 199 adding
control label 198 Broker Server
definition 196 to Broker Administrator
process 201 multiple instances 270
receipt label 198 Broker Server to Broker Servers view 45
source label 197 Broker to Broker Administrator display 45
Access Label Adapter (ALA) 195 Can Publish permission 100
as part of access label process 201 Can Subscribe permission 100
definition 199 client filters 115
failure mode 201 more queue storage 251
acked documents 131 multiple Broker Servers to Broker Administrator 46
ACL ADL (ActiveWorks Definition Language) 76, 81
client group 177 default exported elements 79
definition 275 default imported elements 80
territories 178 definition 81
territory gateways 180 export/import feature 76, 78, 82
ACTIVESW.MIB file 51 exporting to ADL file 76
ActiveWorks Definition Language (ADL) 275 file formats 81
adapter files 55
ALA 195 admin client group 177
and deleting client group 104 administrative access to Broker 169
commit 277 ANSI string, definition 275
dbAdapter 278 applications, uninstalling 71
definition 275 arithmetic operators for filters 160
explicit destroy 95 assigning
gateway filter 159 Can Publish and Can Subscribe permissions 100
information on Broker Server Information page 34 default status to a Broker 67
language 121 Log Publish and Log Acknowledge permissions 102
load balancing 281 properties to client group 20
mutliple sessions 122 async storage configuration flag 57
request document 282 asynchronous write mode 57

Index
authentication configuration data storage 55, 85

enabling server_conf_backup command line tool 86
for client group ACL 177 SSL certificate files 89
for territory SSL 179 system configuration data 74
awbroker process system configuration data storage 85
as part of Broker Server processes 62 multiple territories and gateways 86
Broker Server 52, 63 behavior, Broker client 123
shutting down Broker Server 63 Broker
awbroker.cfg file ACL, See ACL 176
backing up 82 activity, logging 50
changing storage cache size in 57 adding to Broker Administrator display 45
max-cache-size=nnn entry 57 administrative access to 169
server_config add 237 assigning default status to 67
server_config create 237 backing up system config data 85
awbrokermon process command line utilties, See command line utilities 232
as part of Broker Server processes 62 commands, list of 232
Brioker Server Monitor 52 configuration information 74
Broker Monitor 63 copying
broker_stop and broker_start 262 Broker information 75
shutting down Broker Server 63 info from one Broker to another 53
awbrokermon.cfg file 58 creating 66
disable Broker Monitor logging 59 creating default Broker 66
key values in 59 data directory 83
re-enable Broker Monitor logging 60 default
awcert command line tool Broker Information page 38
certificate manager program 185 Brokers page 37
using distinguished names configuring and setting up 23
with 193 create using broker_create 254
awcert list command, to display certificate status 194 installation 18
definition 18, 275
B deleting 70
back up and restore deploying additional 72
Broker Server configuration data storage 85 displaying document types 106
command line utilities 231 gateway 142
of Broker Server combined data storage 82 guaranteed storage 70
of Broker Server configuration data storage 82 higher performance 68
backing up improving performance 69
and restoring, See backup and restore managing document types in 106
awbroker.cfg file 82 maximum number
Broker system config data 85 of clients 272
by exporting system configuration 83 of document types 19
combined storage session 88 per Broker Server 271
configuration data 74 per territory 272

remote publish 145 Broker client
selecting 210 acquiring access label 197
single and multiple sessions 122 behavior, displaying 123, 124
SSL 176, 177 client state, See client state
using Clipboard feature of Broker Administrator to copy info default setting of one active session 122
75, 77 definition 19, 276
Broker Administrator 20, 33 deleting 125
adding destroying when disconnecting 122
Broker Server to 45 displaying 114
multiple Broker Servers to 46 group, See client group
multiple instances of Broker Server to 270 information 116
administering Broker Servers 44 life cycle 94
Broker clients, managing 114 life cycle properties 95
certificate 33 managing 113, 114
changing Broker status 67 multiple sessions 122
Clipboard feature 75, 77 name limitations 71
connection settings 32 queue storage properties 97
deploying additional Brokers 72 queue, See queue 119
document types, managing 106 removing subscriptions 124
export feature 76, 78, 82 sessions 122
exporting Broker Server configuration 83 state sharing 117
identity settings 33 subscriptions 120
import feature 76, 78, 82 Broker Monitor
Integration Server 28 awbrokermon process 63
introduction 20 Broker Server processes 62
known configuring logging 58
servers 31 default values in awbrokermon.cfg file 59
territories 31 disabling logging 59
known servers 33 logging
known territories 33 default enabled 58
logging on 26 disabling 59
navigating in 28 re-enabling logging 60
Navigation panel, views 29 Broker Server
refreshing main page 31 ACL, See ACL 176
removing Broker Servers from 47 adding 236
setting up administering 44
client groups 93 awbroker process 63
permissions 32 backing up configuration data storage 85
SSL 33 command line utilties, See command line utilities 230
starting 26 configuration
starting Broker Server 61 copying 53
stopping Broker Server 61 information 74
updating information 31 configuring 23
Utilization page 48

Index
copying save command 260

info from one Broker to another 53 ADL file 76
information 75 exporting Broker info 76
creating 237 exporting Broker Server configuration 83
default 44 using to copy Broker info 77
definition 284 start command 262
error messages 273 starting a Broker Server 61
executable and server_config add 236 status command 265
host, definition 18, 284 displaying Broker statistics 36
installation 23 setting up Broker Server 23
list file, creating 46
stop command 262
listing 246
stopping a Broker Server 61
maximum number of territories 272
BrokerConfig.qs.log log file
name limitations 71
configuration (metatdata) storage session 239
overview 18
BrokerConfig.qs.stor storage file
processes 62
properties, displaying 34 configuration (metatdata) storage session 239
removing 47 Brokers joining territories
setting up 23 multiple Brokers 141
shutting down on Solaris, HP-UX, and Windows platforms 63
statistics, displaying 34 C
stopping and starting 61 callback, definition 276
updating configuration 252 Can Publish permissions
usage information 48 adding 100
usage statistics 48 removing 101
Utilization page 48 Can Subscribe permissions
working with multiple instances 270 adding 100
Broker Servers view 29 removing 101
adding Broker Server 45 certificate
Broker System Log exporting single certificate 191
display 52 certificate files
exporting from Broker Administrator 52
certificates, See certificates
purging from Broker Administrator 53
changing to an exportable format 192
broker_
copying all certificates 191
buildall command 253
creating and managing 183
config, See server_config
definition 276
create command 254
exporting a single certificate 191
creating new Broker 66
passwords, changing 193
delete command 256
deleting Broker 70 removing certificates 192
load command 257 certificate manager
exporting Broker info 76 awcert command line tool 185
exporting Broker Server configuration 83 certificates 190
restoring system configuration using ADL import 84 definition 276
ping command 259 trusted roots 189

certificates client program
additional operations with certificate manager 190 Broker clients 114
copying 191 definition 277
definition 276 distinguised name/user name 121
deleting 192 managing Broker sessions 122
exporting single 191 client queue
files, See certificate files See also queue
installing 188 definition
listing 190 storage types 95, 97
removing from a certificate file 192 client state
requests, generating 187 definition 19, 277
status 194 Destroy on Disconnect 278
viewing list of 190 Destroy on disconnect 95
Certification Authority (CA) 164 destroying when deleting client 125
definition 276 Explicity destroy 280
CLASSPATH life cycle 281
definition 276 load balancing 281
of JAR and class files 209 multiple clients sharing same client state 123
client Clipboard feature of Broker Administrator
See also Broker client copyijng Broker information 75, 77
connection type, definition 276 combined data storage
filters 33, 115 backup and restore 82
group, See client group combined storage session 238
program, See client program asynchronous write mode 58
queue disaster recovery 82
See client queue server_config storage command line tool 248
state, See client state storage cache size 56
client group command line utilities 229–265
ACL 177 awcert 193
activity 97 Broker 232
admin 177 broker_buildall 253
client life cycle 94 broker_config, See server_config
configuring 99 broker_create 254
creating 99 broker_delete 256
definition 20, 277 broker_load 257
deleting 104 broker_ping 259
description 103 broker_save 260
displaying list of 98 broker_start 262
name limitations 71 broker_status 265
properties 20, 94 broker_stop 262
setting up 93 copying Broker and Broker Server info 76, 77
SSL 177 list of 21, 229
server_conf_backup 232

Index
server_conf_restore 234 confirming Broker connection for gateway 155

server_config add 236, 237 connection
server_config delete 245 confirming for gateway 155
server_config help 246 factories, definition 212
server_config list 246 queue connection factory administration
server_config remove 247 settings for Broker Administrator 32
server_config start 247 status of Broker 37, 38
server_config stop 247 timeout default value for Broker Administrator 32
server_config storage 248 timeout value for JMS Broker connection 211
server_config update 252 topic connection factory administration 220
commit Connection Client ID, setting 214, 220
definition 277 content-based security 195
logged commit in guaranteed storage 70 context factory, initial 208
manually performing 133 control container, definition 277
transactions state 130 control label 198
Committed transaction state 131 conventions used in this document 13
configuration (metadata) storage 237 copying
diagram of 55 all certificates 191
separate storage session 55, 238 Broker information 75
configuration data 83 from one Broker to another 53
backing up 74 Broker Server information 75
copying 74 configuration 53
disaster recovery 82 from one Broker Server to another 53
exporting 83 certificates 191
exporting using ADL 82 system configuration data 74
importing system configuration 84 trusted roots 191
point-in time recovery 82 using
saving and restoring 82 ADL export/import feature 78
storage, See configuration data storage broker_save command line tool 77
configuration data storage Clipboard feature of Broker Administrator 77
backing up 55, 85 command line tools 77
backup and restore 82 using command line tools 76
command line utilities 231 creating
server_conf_restore command line tool 234
additional storage 251
storage cache size 56
Broker Server list file 46
configuring
Brokers 66
Broker Monitor logging 58
client group 99
Broker Server for SSL 171
default Broker 66
installed on different host 174
default Broker with broker_create 254
client group 99
default Broker 23 separate storage session 238
log options 50 territories 138
territory gateways territory gateway
both Brokers 154 both Brokers 154
one Broker 157 one Broker 157

D log file size on installation 96
data directory, Broker 83 logging on values
data field Broker 27
definition 277 JMS Administrator 207
document type 111 native logging facility 50
data files, Broker 83 port
dbAdapter JMS Administrator 206
definition 278 port main -1 194
explicit destroy 95 port main -2 194
request document 282 port number 6849 26, 44, 194
S field 279 prefix when naming JMS objects and subcontexts 213
trigger 283 -qs_log file
default server_config create 240, 244
active session per Broker client 122 server_config storage 250
ADL export elements 79 -qs_storage file
ADL file format 81 server_config create 241, 244
ADL import elements 80 server_config storage 251
authenticator names 179 recent deliveries value 37, 140
Broker recover mode for XA transactions 132
assigning 67 -session_config qs
configuring and setting up 23 server_config create 239, 243
creating new Broker 66 server_config storage 249
during installation 18 shared
on Broker Information page 38 document order for JMS Administrator 117
on Brokers page 37 state ordering for JMS Administrator 218
to create using broker_create 254 state setting for JMS Administrator 218
Broker Monitor SSL encryption
logging enabled 58 connection factory 221
values in awbrokermon.cfg file 59 JMS Administrator 214
Broker Server 44 not to use as default 165
broker_ping sends one document 259 setting 32
client filters 33 storage configuration for new Broker installations 85
combined storage session files 243 storage file 49
connection sharing and encryption settings for JMS name 241
Administrator 217 sizes 96
data files, location of 231 sizes on installation 96
document time interval between statistical polls 33
traffic value for Territories view 29 Time to Live (TTL) attribute 109
type validation 110 timeout connection value on Broker Administrator 32
guaranteed storage size 96 transaction commit 132
keep alive interval 150 updating information on Broker Administrator 31
key_length value for key pairs 187 Write UNIX Syslog 51
local5 51

Index
deleting Broker Server usage 48

Broker client 125 Broker statistics 36
Brokers 70 Broker System Log page 52
certificates 192 client groups
client group 104 activity 97
subscriptions 124 list of 98
deliver 145 client queue
Access Label Adapter (ALA) 200 properties of client group 97
definition 278 statistics 119
remote publish 145 connection
subscribe permission 100 factory information 221
territories 147 status 37, 38
deploying document types 106
additional Brokers 72 documents in client queue 119
multiple Broker, using clipboard to copy info 75 error log 50
destinations 212 gateway information 148
destroy on disconnect 95 help comands from the command line 230
client 276 JMS Administrator and Broker settings 211
definition 278 JMS Administrator queue information 218
destroying license expiration information 35
Broker client when disconnecting 122 life cycles properties of client group 97
client state when deleting client 125
queue connection factory information 215
lost transactions 133
sessions 120
queue when deleting Broker client 124
shared document type list 151
Digital Signature Algorithm (DSA) 279
statistics from the command line 265
Digital Signature Standard (DSS) 279
status of certificate 194
disabling
subscription 120
filter strings 111
document type validation 110
territoriy information 139
state sharing for Broker client 117
topic information in JMS Administrator 225
static gateway forwarding 153
transactions, hueristically completed 134
disaster recovery
distinguished name 166
backing up system configuration immediately after making
config changes 74, 85 access label 196
of Broker and Broker Server combined data storage 82 Broker SSL setting 212
of Broker and Broker Server configuration data 82 definition 166, 278
Discover Broker Server option 45 exporting certificate associated with 191
using with awcert 193
displaying
document
See also viewing
and refreshing information on Broker Administrator 31 definition 19, 278
Broker Administrator Navigation panel 29 envelope, definition 279
Broker client 114 filtering 159
behavior 124 folder
information 116 definition 279
Broker properties 34 description of 19

guaranteed 69 encryption
in client queue 119 definition 164, 280
reply document 281 public key 164
size, maximum 69 strength of webMethods Broker 192
traffic, default value 29 End Failure transaction state 130
traffic, recent deliveries 37, 140 End Success transaction state 130
type, See document type enqueue traces 148
volatile 70 error log
Document type Broker Server error messages 273
logging 67 viewing 50
document type Event Log, Windows 51
data field 111 event, See also document
definition 19, 279 expiration of access labels
displaying 106
access label
displaying list of 106
expiration of 203
Force Join 141
explicit destroy 95
logging 103
definition 280
managing 106
multi-connection client 276
maximum number 19
name limitations 71 Export Log option
publish and subscribe permissions 100 messages in log file 52
shared, list of 151 exportable format, changing certificate files to 192
storage 95, 97 exporting 83
storage types 109 Broker information 76
Time To Live attribute 109 broker_save 76
validation 108, 110 broker_load command line tool 76
validation level 110 broker_save command line tool 76
documentation certificate 191
additional 14 single certificates 191
conventions used 13 system configuration data
feedback 14 using ADL 82
DSA standard 164 to ADL file 76
definition 279 using ADL 76, 78, 81, 82
E F
enabling failure mode, ALA 201
access control files
for client group ACL 177
ACTIVESW.MIB 51
for territory SSL 179
ADL 55
authentication
formats 81
for client group ACL 177
awbroker.cfg 57
for territory SSL 179
awbrokermon.cfg 58, 59
state sharing for Broker client 117 Broker Monitor’s configuration file 58
static gateway forwarding 153 Broker Server List 46

Index
configuration storage 56 heuristically completed transactions 131

data directory 44 displaying 134
log 52 HP-UX
SSL certificate, creating and managing 183 error messages log file 273
storage 49 setting maximum thread limit for 269
swap 68 shutting down Broker processes 64, 264
syslog 51 syslog 51
filtering, definition 280
filters I
arithmetic operators 160 importing
client 115 from command line 257
documents 159 system configuration 84
filter string rules 160 using ADL 76, 78, 82
subscription 111 improving performance on your Broker 69
territory gateway 159 initial context factory 208
firewalls installing
definition 280 Broker Server 23
opening port through 194 certificates 188
preventing gateway disconnection from 154 trusted roots 186
with SSL 194 Integration Server
working with 194 and Broker 20
Force Join 141 and JMS Administrator 22
frame, definition 280 documentation 28
logging with 103
G introduction 20
gateway Broker 142
definition 280
J
gateways, See territory gateways Java client classes, definition 281
generating certificate requests 187 JMS
Glossary of terms 275–284 Broker, See JMS Broker 210
graph, territory 142 logging for JMS clients 123
guaranteed documents 69 XA transactions recover mode 132
guaranteed storage 70, 96 JMS administered objects 205–226
Broker selection 210
default size 96
JNDI provider selection 207
files 96
queue connection factories 213
Queue Storage 70
queues 217
type, definition of 282
topic connection factories 220
Gzip data compression program 53
topics 223
JMS Administrator, See webMethods JMS Administrator
H JMS Broker
help from server_config help command line 246 maintaining a list of 210
Heuristic Commit transaction state 130 SSL setting 212
Heuristic Rollback transaction state 130 timeout value setting 211

JNDI provider log options, configuring 50
selecting 206, 207 Log Publish types 94, 99, 102
uploading properties file 209 logging
joining territories 141 Broker activity 50
Broker Monitor, configuring 58
K default native logging facility 50
key_length 187 with Integration Server 103
keystore, definition 166 logging on default values
known servers 31 for Broker 27
Broker Administrator 33 for JMS Administrator 207
known territories 31, 33
M
L managing
LDAP Broker clients 114
JMS object naming conventions 213 territories 138
schema validation 207 max-cache-size 56
leaving territories 142 and asynchronous write mode 57
license key max-cache-size=nnn entry 57
for SSL 172 storage cache 56
webMethods Broker, updating 49 maximum
life cycles document size 69
client 94 size for storage files 96
definition 281 size of document 19
destroy on disconnect 95 thread limit for HP-UX 269
explicit destroy 95 metadata storage, See configuration (metadata) storage
properties of client group 97 monitoring
limitations Broker client
maximum document types on Broker 19 activity and statistical information 114
maximum size of document 19 behavior 123
listing Broker Server usage 48
certificates 190 transactions 130
trusted roots 189 multiple Broker Servers 46
load balancing 281 adding to Broker Administrator 45
definition 281 instances of a single Broker Server 270
shared state 282 server_config create 237
localhost 270 multiple Brokers
Log Ack types 94, 99, 102 and ALAs 201
log files and awbroker process 63
BrokerConfig.qs.log 239 deploying 72
changing sizes using server_config storage 248 joining territory 141
configuration (metatdata) storage session 239 multiple client sessions 122
default size 96
syslog 51

Index
N private key 281

name limitations, Broker Server 71 processes
native (locally editable) ADL file format 81 awbroker 62
navigating in Broker Administrator 28 awbrokermon 62
network connection program code conventions in this document 13
working without 270 properties
Broker Server 34
client group 20, 94
O
displaying 34
online backup life cycle 95
configuration data storage 55, 85
public key encryption 164, 281
Open transaction state 130 definition 281
opening port through firewall 194
publish
operators, filter 160
access 94
across gateway 145
P client group information 98
panel, definition 281 definition 281
passwords docuements in queue information 119
certificate file 193 document type information 107
certificate files 193 document types 98
pausing activity on a gateway 152 maximum document size 69
permissions permissions 100
Can Publish and Can Subscribe 100, 102 JMS Administrator 222
Log Publish types and Log Ack types 102 remote 145
Persistent storage 96, 97 remote publish 145
files 96 shared document types information 152
PKCS #10 format 187 volatile documents 70
platform independent ADL file format 81 publisher
point-in time recovery and access labels 195
of Broker and Broker Server configuration data 82 awbroker process 62
point-in-time recovery remote publish 145
backing up system configuraiton data 75 shared document order 117
exporting system configuration before making config changes shared state ordering
75, 82 JMS 218, 224
of Broker and Broker Server configuration data 82 purging
restoring system configuration through ADL import 84 Broker System Log 53
port entries in error log 52
default port number 6849 26, 44, 194 lost transactions 133
port main-1, default is 6848 194 message log 53
port main-2, default is 6847 194
post-prepare stage of transaction 132
Prepared transaction state 131
pre-prepare stage of transaction 131

Q remote Broker Server 32
queue remote publish 145
See also client queue trace 148
connection, See queue connection factory remote territory
creating using webMethods JMS Administrator 217 static gateway forwarding 153
displaying documents in 119 removing
JMS Administrator 218 Broker client subscriptions 124
local documents waiting to be published 150 Broker Server 47
modifying 219 Can Publish and Can Subscribe permissions 101
properties of client group 97 certificates from a certificate file 192
removing 219 shared document types 158
unacked documents 19 territory gateways 158
viewing information about 218 trusted roots 189
queue connection factory reply document, definition 281
creating 213 request document, definition
modifying 216 document
removing 216 request document 282
viewing information about 215 resource
Queue Storage (QS) 70 definition 282
webmethods Enterprise 284
R restoring
RDBMS, definition 281 and backing up, See backup and restore
receipt label 198 and saving system configuration data 82
Recover Mode 132 Broker Server’s configuration data storage 85
re-enabling Broker Monitor logging 60 system configuration data
refreshing using server_conf_backup command line tool 87
and displaying information on Broker Administrator 31 sytem configuration data 82
relational database management system 281 resuming activity on a gateway 152
remote Broker rollback
behavior 146 definition 282
Can Subscribe/Can Publish information 152 manually performing 133
configuring transaction state 131
gateway 157 RSA
to be a gateway Broker 143 definition 282
connection status 139 standard 164
definition 281 rules
gateway filter strings 160
filters 159 for territories 137
information 150 run-time data storage 237
pinging 260
asynchronous write mode 58
publish 145
diagram of 55
remobing territory gateway 158
separate storage session 238
removing shared document type 158
storage cache size 56
SSL across territory gateways 180

Index
S Services dialog box, Windows 61

S, definition 279 sessions
savepoint, definition 282 Broker client 122
saving displaying 120
and restoring system configuration data 82 setting up
sytem configuration data 82 Broker Server 23
scalability, webMethods Broker 271 client groups 93
search record, definition 282 shared document type, removing 158
secure sockets shared state
definition 282 attribute and multiple sessions 122
modes of 165 definition 282
SSL 164 queues 218
Secure Sockets Layer, see SSL topic connection factories 224, 225
security shutting down Broker processes
access control 195 diagram of Broker Server processes 62
certificate 212 on HP-UX 64, 264
content-based 195 on Solaris 63, 264
credentials 208 on Windows 64
distinguished name 212 SNMP traps 51
principal 208 Solaris platform
separate storage sessions error messages log file 273
creating 238 example for higher performance settings 68
default configuration upon new installation 85 shutting down Broker processes 63, 264
diagram of 55 syslog 51
server_config create 237 source label 197
server_config storage command line tool 248 SSL
storage caches 56 a brief description of 164
server_conf_ backing up 89
backup command line tool 232
Broker 176, 177
restore command line tool 87, 234
Broker Administrator 173
server_config
certificate files, creating and managing 183
add command line tool 236, 237
client group access 177
Broker Server commands 230
configuring Broker Server 171
creating storage (config and data) files 237
default is not to use 165
delete command line tool 245
definition 282
help command line tool 246
list command line tool 246 described 164
list subcommand 246 distinguished name 166
remove command line tool 247 encryption on JMS Administrator 214
start command line tool 247 encryption setting 214, 221
stop command line tool 247 default value 32
storage command line tool 248 for Broker Server installed on a different host than the host
update command line tool 252 running Broker Administrator 174
with 4.x or earlier 231 gateways versus territories 183

keystore 166 displaying 36
license key 172 documents
modes of secure Sockets 165 delivery 265
public key encryption 164 documents in queue 115, 119
roadmap for implementing with webMethods Broker 170 gateway 148
secure sockets 164 remote broker
settings for a Broker 212 can publish 152
standard 164 can subscribe 152
support in Broker 167 time interval between polls 33
territories, within 178 stopping Broker Server 61
territory gateways 180 from Broker Administrator 61
trusted roots 165 from Windows Services 61
using through firewalls 194 storage cache sizes 56
using webMethods Broker with 167 storage files
standard BrokerConfig.qs.stor 239
DSA 164 changing sizes of 248
PKCS #10 187 changing sizes using server_config storage 248
RSA 164 configuration (metatdata) storage session 239
SSL 164 configuration default for new installations is separate storage
X.509 188 sessions 85
starting default .stor file 49
Broker Administrator 26 default size 96
logging on 26 default sizes on installation 96
Broker Server 61 Guaranteed 96
from Broker Administrator 61 maximum size 96
from Windows Services 61 Persistent 96
JMS Administrator 206 server_config create 237
state sizes 248
client 19, 277 storage sessions
sharing for Broker client 117 combined 238
transaction 130 configuration (metadata) 237, 238
static gateway forwarding 153 run-time data 237, 238
details 151 storage system
enabling/disabling 153 configuration data 74
statistics configuration default for new installations is separate storage
Broker Information page 38 sessions 85
Broker Server 34 storage caches 56
Information page 34 storage types
usage 48 client queue 95, 97
broker_status 265 definition 282
client 265 document type 109
groups 98 Guaranteed 96
command line 265 Persistent 96
Volatile 96

Index
subgroup, definition 282 rules for 137

subscribe SSL within 178
access 94 system configuration 74
across gateway 145 Territories view 29
permissions 100 territory graph 142
JMS Administrator 222 unique names for 138
subscriber territory gateways
awbroker process 62 access labels 203
static gateway forwarding 153 ACL 180
subscription configuring
and Access Label Adapter (ALA) 199 both Brokers 154
and static gateway forwarding 153 one Broker 157
Client Information page 116 process 143
client state information 19 configuring SSL
definition 283 for both Brokers 181
deleting 124 for one Broker 182
displaying 120 creating
Document Types page 107 both Brokers 154
filter strings 111 one Broker 157
filtering 280 definition 142, 283
removing 124 displaying information about 148
Subscriptions page 120 filters 159
swap file 68 gateway Broker 142
system configuration data information, displaying 148
See also configuration data overview 142
Broker 74 pausing activity on 152
Broker Server 74 preventing firewall disconnections 154
removing
T a shared document type 158
territories gateway 158
ACL 178 resuming activity on 152
creating 138 shared document type list
definition 18, 283 both Brokers 155
Force Join 141 one Broker 158
gateway, See territory gateways SSL 180
graph 142 static gateway forwarding 153
information, displaying 139 system configuration 74
information, viewing 139 Time to Live attribute 109
joining 141 default value 109
leaving 142 timeout value
managing 138 default for Broker Administrator connection 32
multiple 141 for JMS Broker connection 211
overview 136 transaction 131

tools, command line See command line utilities described 165
topic installing 186
creating 223 listing 189
removing 225 removing 189
viewing information about 225 viewing list of 189
topic connection factory TTL, See Time to Live attribute
creating 220 typographical conventions in this document 13
modifying 222
removing 223 U
viewing information about 221 unacked documents 19
traces Unicode
enqueue 148 characters in ADL file formats 81
pinging a remote Broker 260 Transform Function 8 (UTF-8) 283
remote publish 148 uninstalling applications 71
transaction unique names for territories 138
and guaranteed storage 70 UNIX
commit 133, 277 Broker Monitor logging 59
controls 130 command line utilities 21
default value is to commit 132 CPU usage statistic 48
definition 283 default data files location 231
destroying lost transactions 133 Gzip data compression program 53
heuristically completed 131 Syslog 51
information 130 updating
number of executing on Broker 39 Broker Administrator 31
post-prepare stage 132 webMethods Broker license key 49
pre-prepare stage 131 Upload Broker Server List option 45, 46
purging lost transactions 133 usage statistics of Broker Server 48
Recover Mode 132 using
roll back 133, 282 access labels 197
size part of total storage space 49 transaction controls 130
states 130 UTF-8, definition 283
timeout option 131 Utility Logger 67
viewing lost transactions 133 logging with Integration Server 103
viewing running transactions 130 Utilization page 48
XA 132
trigger
V
client filters 33
validation
definition 283
troubleshooting information 14 certificate 166
document type 108, 110
trusted roots
versioning, definition 284
additional operations with certificate manager 189
copying 191 viewing
See also displaying
definition 165, 283
Broker Administrator 29

Index
Broker Administrator connection settings 32 X

Broker client activity and statistical information 114 X.509 digital certificate 188
certificates 190 XA transactions, recover mode 132
client filters 33
lost transactions 133
running transactions 130
territory information 139
trusted roots 189
volatile documents 70
Volatile storage 96, 97
definition of storage type 282
W
WARNINGS
broker_load program, large files 257
import file command, large files 80
webMethods Broker
Administrator, see Broker Administrator 20
definition 284
implementing SSL 170
scalability 271
system, shutting down 62
using SSL with 167
webMethods Enterprise resource, definition 284
webMethods JMS Administrator 22, 205–226
Broker selection 210
connection factories 212
destinations 212
JNDI provider selection 207
queue connection factories 213
queues 217
staring 206
topic connection factories 220
topics 223
Windows platform
command line utilities 21
default data files location 231
error messages log file 273
Event Log, Broker Administrator 51
shutting down Broker Server on 64
Windows Services
dialog box 61
starting server 61
stopping server 61

Broker Admin Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Broker Admin Guide

Uploaded by

Copyright:

Available Formats

webMethods Broker

Document ID: BR-AG-65-20050615

About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Part I. Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Chapter 1. Overview of webMethods Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Chapter 2. Using the webMethods Broker Management Tools . . . . . . . . . . . . . . . . . . . . . 25

webMethods Broker Administrator’s Guide Version 6.5 3

Part II. Broker Server and Broker Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Chapter 3. Managing webMethods Broker Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Chapter 4. Managing Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

4 webMethods Broker Administrator’s Guide Version 6.5

Part III. Client Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Chapter 6. Managing Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

webMethods Broker Administrator’s Guide Version 6.5 5

Chapter 7. Managing Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Chapter 8. Managing Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Part IV. webMethods Broker Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Chapter 9. Monitoring and Managing Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

6 webMethods Broker Administrator’s Guide Version 6.5

Chapter 11. Managing Broker Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

webMethods Broker Administrator’s Guide Version 6.5 7

A Roadmap for Implementing SSL Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

8 webMethods Broker Administrator’s Guide Version 6.5

Part V. Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

Appendix A. webMethods Broker Command Line Utilities . . . . . . . . . . . . . . . . . . . . . . . . . 229

webMethods Broker Administrator’s Guide Version 6.5 9

server_config start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

Appendix B. Tips and Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

10 webMethods Broker Administrator’s Guide Version 6.5

About This Guide

Basic concepts of webMethods Broker architecture

webMethods Broker Administrator’s Guide Version 6.5 13

14 webMethods Broker Administrator’s Guide Version 6.5

Overview of webMethods Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Using the webMethods Broker Management Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

webMethods Broker Administrator’s Guide Version 6.5 15

webMethods Broker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

webMethods Broker Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Setting Up a webMethods Broker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

webMethods Broker Administrator’s Guide Version 6.5 17

webMethods Broker Server

Broker Server Host

18 webMethods Broker Administrator’s Guide Version 6.5

different Broker Server, if desired. In addition, territories can be linked by territory

Queue of documents not yet acknowledged (“unacked” documents)

webMethods Broker Administrator’s Guide Version 6.5 19

Client queue storage type

Subscribe and publish access to document types

Access control list

webMethods Broker Management

20 webMethods Broker Administrator’s Guide Version 6.5

Command Line Utilities

Command Line Utilities Description

webMethods Broker Administrator’s Guide Version 6.5 21

Command Line Utilities Description

webMethods JMS Administrator

22 webMethods Broker Administrator’s Guide Version 6.5

Setting Up a webMethods Broker Server

To set up a webMethods Broker Server

1 Install the webMethods Broker software.

webMethods Broker Administrator’s Guide Version 6.5 23

24 webMethods Broker Administrator’s Guide Version 6.5

Starting the webMethods Broker Management Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Quick Tour of Broker Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

1 From the Start menu choose ProgramswebMethodsServersIntegration Server to start