Broker Admin Guide

webMethods Broker
Administrator’s Guide
VERSION 6.1
webMethods, Inc.
3930 Pender Drive
Fairfax, VA 22030
USA
703.460.2500
http://www.webmethods.com
webMethods Administrator, webMethods Broker, webMethods Dashboard, webMethods Developer, webMethods Glue, webMethods Fabric, webMethods
Installer, webMethods Integration Server, webMethods Mainframe, webMethods Manager, webMethods Mobile, webMethods Modeler, webMethods
Monitor, webMethods Optimize, webMethods Trading Networks, webMethods Workflow, and the webMethods logo are trademarks of webMethods, Inc.
"webMethods" is a registered trademark of webMethods, Inc.
Acrobat, Adobe, and Reader are registered trademarks of Adobe Systems Incorporated. Amdocs and ClarifyCRM are registered trademarks of Amdocs Ltd.
Ariba is a registered trademark of Ariba Inc. BEA is a registered trademark, and BEA WebLogic Platform and BEA WebLogic Server are trademarks of BEA
Systems, Inc. BMC Software and PATROL are registered trademarks of BMC Software, Inc. BroadVision is a registered trademark of BroadVision, Inc. Chem
eStandards and CIDX are trademarks of Chemical Industry Data Exchange. Unicenter is a registered trademark of Computer Associates International, Inc.
Kenan and Arbor are registered trademarks of CSG Systems, Incorporated. SNAP-IX is a registered trademark, and Data Connection is a trademark of Data
Connection Ltd. DataDirect, DataDirect Connect, and SequeLink are registered trademarks of DataDirect Technologies. D&B and D-U-N-S are registered
trademarks of D&B, Inc. Entrust is a registered trademark of Entrust. 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, IBM, Infoprint, Informix, MQSeries, OS/390, OS/400, RACF, RS/6000,
SQL/400, S/390, System/390, VTAM, and WebSphere are registered trademarks; and Communications System for Windows NT, IMS, MVS, SQL/DS, Universal
Database, and z/OS are trademarks of IBM Corporation. JBoss and JBoss Group are trademarks of Marc Fleury under operation by JBoss Group, LLC. J.D.
Edwards and OneWorld are registered trademarks, and WorldSoftware is a trademark of J.D. Edwards. Linux is a registered trademark of Linus Torvalds and
others. X Window System is a trademark of Massachusetts Institute of Technology. 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. Teradata is
a registered trademark of NCR. Netscape is a registered trademark of Netscape Communications Corporation. New Atlanta and ServletExec are trademarks
of New Atlanta Communications, LLC. CORBA is a registered trademark of Object Management Group, Inc. UNIX is a registered trademark of Open Group.
Oracle is a registered trademark of Oracle Corporation. PeopleSoft and Vantive are registered trademarks, and PeopleSoft Pure Internet Architecture is a
trademark 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 trademarks or registered trademarks of SAP AG. Siebel is a trademark of Siebel Systems, Inc. SPARC and SPARCStation are trademarks of
SPARC International, Inc. SSA Global is a trademark and SSA Baan is a registered trademark of SSA Global Technologies, Inc. EJB, Enterprise JavaBeans, Java,
Java Naming and Directory Interface, JavaServer Pages, JDBC, JSP, J2EE, Solaris, Sun Microsystems, and SunSoft are trademarks of Sun Microsystems, Inc.
SWIFT and SWIFTNet are trademarks of S.W.I.F.T. SCRL. Sybase is a registered trademark of Sybase, Inc. UCCnet is a trademark of UCCnet. eBusinessReady
is a trademark of Uniform Code Council, Inc. (UCC) and Drummond Group, Inc. (DGI). Verisign is a registered trademark of Verisign. VERITAS, VERITAS
SOFTWARE, and VERITAS Cluster Server are trademarks of VERITAS Software. W3C is a registered trademark of World Wide Web Consortium.
All other marks are the property of their respective owners.
Copyright © 2004 by webMethods, Inc. All rights reserved, including the right of reproduction in whole or in part in any form.
Document ID: BR-AG-61-20040116

Contents
Contents
About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

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

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

Starting the webMethods Broker Management Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Logging On to Broker Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Quick Tour of Broker Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Viewing Broker Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Notes on Using Broker Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Customizing the View of Broker Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Sorting Information in Broker Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Updating Information on Broker Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Setting Up Broker Administrator Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Viewing and Changing Connection Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Viewing and Changing Client Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Viewing and Changing Identity Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Basic Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Displaying webMethods Broker Server Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
webMethods Broker Administrator’s Guide Version 6.1 3

Contents
Displaying Broker Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

The Brokers Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Part II. Broker Server and Broker Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Chapter 3. Managing webMethods Broker Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Managing the webMethods Broker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Creating a webMethods Broker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Adding a Broker Server to Broker Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Adding Multiple Broker Servers to Broker Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Creating a Broker Server List File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Importing a Broker Server List File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Removing a Broker Server from the Broker Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Monitoring webMethods Broker Server Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
About Memory (Swap Space) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Updating the webMethods Broker Software License Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Logging webMethods Broker Server Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Configuring Log Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Using the Broker System Log Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Copying webMethods Broker Server and Broker Information . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Methods of Copying Broker Server and Broker Information . . . . . . . . . . . . . . . . . . . . . . . . 53
Copying Broker Server and Broker Information Using the Import/Export Feature of the Broker
Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
File Formats for Broker and Broker Server Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . 57
Configuring webMethods Broker Servers from the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Configuring the Storage Cache Size for a webMethods Broker Server . . . . . . . . . . . . . . . . . . . . . . . 58
Stopping and Starting a webMethods Broker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Shutting Down the webMethods Broker System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
webMethods Broker Server Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Chapter 4. Managing Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Managing Individual Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Creating New Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Assigning Default Status to a Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Enabling Document Type Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Setting Up Your webMethods Broker for Higher Performance . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Improving Your Broker Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
webMethods Broker Document Sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Broker's Guaranteed Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
4 webMethods Broker Administrator’s Guide Version 6.1

Contents
Deleting Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Name Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Uninstalling Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Deploying Additional Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Copying Broker Information Using the Clipboard Feature of the Broker Administrator . . . . . . . . 70
Chapter 5. Saving and Restoring Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Saving and Restoring System Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Saving System Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Saving Broker Server Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Saving Broker Server Configurations from the Command Line . . . . . . . . . . . . . . . . . . . . . . 75
Restoring System Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Backing Up webMethods Broker Server Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Backing Up webMethods Broker Server Data Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Restoring the webMethods Broker Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Part III. Client Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Chapter 6. Managing Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Understanding Client Group Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Lifecycle Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Client Queue Storage Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Maximum Storage File Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Client Queue Storage Versus Document Type Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Displaying Client Group Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Creating and Configuring a Client Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Creating a Client Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Assigning “Can Publish” and “Can Subscribe” Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Adding “Can Publish” and “Can Subscribe” Permission . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Removing Can Publish and Can Subscribe Permission . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Assigning Log Publish and Log Acknowledge Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Changing a Client Group Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Setting the Client Group Encryption Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Deleting a Client Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Chapter 7. Managing Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
About Managing Document Types in a Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Displaying the Document Types in a Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Contents
Editing Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Document Type Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Document Type Storage Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Document Time to Live . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Document Type Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Data Field Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Displaying Subscription Filter Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Chapter 8. Managing Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Viewing Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Displaying Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Client Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Displaying Broker Client Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Displaying Documents in a Client Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Displaying the Subscriptions Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Displaying the Sessions Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Managing Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Managing Broker Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Disconnecting Broker Client Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Managing Client Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Clearing Documents in a Client Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Monitoring Broker Client Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Displaying Broker Client Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Controlling Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Removing a Broker Client Subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Disconnecting a Broker Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Deleting a Broker Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Part IV. webMethods Broker Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Chapter 9. Monitoring and Managing Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Using Transaction Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Viewing Running Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Setting the Timeout Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Manually Performing a Commit or Roll Back . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Viewing and Purging Lost Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Contents
Chapter 10. Territories and Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Rules Concerning Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Unique Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Managing Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Creating a Territory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Viewing Territory Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Joining a Territory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Leaving a Territory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Territory Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Using Broker Remote Publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Broker Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Displaying Gateway Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Displaying the Shared Document Type List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Pausing or Resuming a Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Preventing Firewall Disconnections of Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Configuring a Gateway if You Control Both Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Creating the Gateway (Both Brokers) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Configuring the Shared Document Type List (Both Brokers) . . . . . . . . . . . . . . . . . . . . . . . 142
Configuring a Gateway If You Control One Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Creating the Gateway (One Broker) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Configuring the Shared Document Type List (One Broker) . . . . . . . . . . . . . . . . . . . . . . . . . 144
Removing a Shared Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Removing a Territory Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Using Gateway Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Filtering Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Filter Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Filter Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Chapter 11. Managing Broker Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Security Using Secure Sockets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
A Brief Description of SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Public Key Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Modes of Secure Sockets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Trusted Roots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Distinguished Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Using webMethods Broker with SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Access Control Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Administrative Access to webMethods Broker Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Administrative Access to Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

Contents
Client Access to Broker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

Administrative Access to Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
A Roadmap for Implementing SSL Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Configuring the webMethods Broker Server for SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Determining If You Have an SSL License Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Preparing the Certificate File for the Broker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Configuring Broker Administrator for SSL Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Enabling SSL for the webMethods Broker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Setting Up Access Lists for the webMethods Broker Server . . . . . . . . . . . . . . . . . . . . . . . 161
Setting Up Client Group Access Control Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Using SSL for Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Using SSL Across Territory Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Enabling SSL If You Control Both Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Enabling SSL If You Control One Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Gateway SSL and Territory SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Creating and Managing SSL Certificate Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Uploading Certificate Files Using the Broker Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Using the Certificate Manager Program (awcert) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Installing Trusted Roots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Generating Key Pairs and Certificate Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Installing Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Additional Operations for Trusted Roots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Listing Trusted Roots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Removing Trusted Roots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Additional Operations for Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Listing Certificates in the Certificate File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Copying All Certificates in a Certificate File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Exporting a Single Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Changing Certificate Files to an Exportable Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Removing Certificates from a Certificate File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Changing the Certificate File Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Using Distinguished Names with awcert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Certificate Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Working with Firewalls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Using SSL through Firewalls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

Contents
Part V. Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Appendix A. webMethods Broker Command Line Utilities . . . . . . . . . . . . . . . . . . . . . . . . . 183

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Broker Server Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Broker Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
server_config add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
server_config create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
server_config delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
server_config help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
server_config list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
server_config remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
server_config start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
server_config stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
server_config storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Configuring the Storage Cache Size for a webMethods Broker Server . . . . . . . . . . . . . . . . . . . 194
server_config update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
broker_buildall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
broker_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
broker_delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
broker_load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
broker_ping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Pinging a Remote Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
broker_save . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
broker_stop and broker_start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
broker_stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
broker_start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Shutting Down the webMethods Broker Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Shutting Down the webMethods Broker Processes on Solaris 2.x . . . . . . . . . . . . . . . . . . . 206
Shutting Down the webMethods Broker Processes on HP-UX . . . . . . . . . . . . . . . . . . . . . . 207
broker_status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Appendix B. Tips and Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

Tips on Using webMethods Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Importing Large ADL Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Increasing the Session Timeout Value for Integration Server . . . . . . . . . . . . . . . . . . . . . . . 210
Importing a Large ADL File Using the broker_load Command Line Utility . . . . . . . . . . . . . 210
Setting Maximum Thread Limit for HP-UX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Working Without a Network Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Working with Multiple Instances of a Single Broker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Contents
Adding Multiple Instances of a Broker Server to Broker Administrator . . . . . . . . . . . . . . . . 212

Scaling the webMethods Broker System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
What is the maximum number of Brokers per webMethods Broker Server? . . . . . . . . . . . . 213
What is the maximum number of Brokers per territory? . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
webMethods Broker Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Glossary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

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.1 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Using the webMethods Broker Management Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

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

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

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 and
command line utilities. 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.
server_config Creates and configures Broker Servers.
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.
broker_buildall Compiles all intelligent integration components and
scripted operations from a Broker.
The command line utilities are described in detail in Appendix A, “webMethods Broker
Command Line Utilities.”

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 34 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 Integration Platform 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.

Setting Up a webMethods Broker Server
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Quick Tour of Broker Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Basic Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

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.”
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 Programs > > Servers > Integration 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/
If the Integration Server is running on port 4040 on a machine called ATLAS, you
would type:
http://ATLAS:4040/WmBrokerAdmin/

Starting the webMethods Broker Management Tools
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).
Note: 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 installs 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.
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/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 Integration Server Online
Reference for 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 28.
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 this 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 42.
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.
IntegrationServer. 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 103.
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 (Settings>Identity) 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 158 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 30.

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 32.
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 the
Deliveries time interval between statistical polls. The default value is
1 minute. To change the default setting, see “Viewing and Changing
Connection Settings” on page 30.
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 66.
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.
Recent The document traffic on the Broker for the last X minutes. Where X is the
Deliveries time interval between statistical polls. The default value is 1 minute. To
change the default setting, see “Viewing and Changing Connection
Settings” on page 30.
Total Total document traffic on the Broker since it was created.
Deliveries
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Managing Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Saving and Restoring Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

CHAPTER 3
Managing webMethods Broker Servers
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Managing the webMethods Broker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Configuring webMethods Broker Servers from the Command Line . . . . . . . . . . . . . . . . . . . 57
Configuring the Storage Cache Size for a webMethods Broker Server . . . . . . . . . . . . . . . . 58
Stopping and Starting a webMethods Broker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Shutting Down the webMethods Broker System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

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 good practice to make regular backups of
the data directory of every Broker Server on a host.
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 atlas is identified as atlas:6840.
The Broker Servers on a host do not have to be the same version of webMethods Broker.
The version of webMethods Broker installed on the host must match the highest version
among the Broker Servers you want to run. This makes it possible to run older versions of
the webMethods Broker, which is useful when the time comes to upgrade from one
version to another.
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 187 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 44.
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 4. 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.
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 64.
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 60.
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 webMethods 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 The percentage of memory, or swap space, available on the
computer is important to the success of Guaranteed storage.
(Every page in the guaranteed storage file should be matched
by a page in memory.) For more information, see “About
Memory (Swap Space)” on page 48.
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 Stats. 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 size of each storage file
– Space reserved per storage file
†Persistent Store Total. Percentage of disk space available at the location used
by persistent storage. The bar appears in red if low disk
space is limiting your use of Persistent storage.
Used. Percentage of persistent storage currently used.
Free. Percentage of remaining disk space that you are

allowed to use for persistent storage.
†Guaranteed Store The percentage of memory, or swap space, available on the
computer is important to the success of guaranteed storage.
(Every page in the guaranteed storage file should be matched
by a page in memory.) For more information, see “About
Memory (Swap Space)” on page 48.
Total. Percentage of disk space available for guaranteed
storage (for Windows only).
Used. Percentage of guaranteed storage currently used.
Free. Percentage of remaining disk space that you are

allowed to use for versions 3.x and 4.x guaranteed storage.
†These statistics are applicable to pre-5.0 Broker Servers only. Due to the improvements
made to Broker Server storage, these statistics are no longer applicable and will not be
displayed on Broker Server versions 5.0 or later.

About Memory (Swap Space)

The amount of swap space available on the computer is important to the success of
Guaranteed storage. Every page in the guaranteed storage file should be matched by a
page in swap space. For example, if you need to store 100MB of guaranteed documents in
a Broker on a Broker Server, you should allocate 100MB of additional swap space. For
information about the maximum file size for Guaranteed storage, see “Maximum Storage
File Size” on page 84.
You can increase the amount of guaranteed storage on the hard disk using the
server_config command-line program. See “server_config storage” on page 192 for
more information.
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 System 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 System 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:
Solaris: /var/log/broker.alert
/var/log/broker.info
AIX: /var/opt/activesw/ broker.alert

/var/opt/activesw/broker.info
HP-UX: /var/adm/syslog/broker.alert
/var/adm/syslog/broker.info
Use the dropdown box to select a facility that is not currently

used by another application. The default is local6.
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.

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.
4 Click Export Broker System 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.
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

Methods of Copying Broker Server and Broker Information

There are a number of methods available for copying broker and broker server
information:
Broker commands
You can use the broker_save command to export broker and broker server
information into an ActiveWorks Definition Language (ADL) file. You can then use
the broker_load command to import the information/ADL file into another broker or
broker server.
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 commands. In addition, and you have the option of
copying subsets of information.
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.
The method you choose depends on your needs.
Use this feature... If you need to..
broker_save and Script the import /export process, especially when moving
broker_load through different environments.
commands
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.
Import/Export Export only a subset of components (for example, only doc
feature of the Broker types, or only client groups) to an ADL file.
Administrator
Save an ADL file to disk, but don’t 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.

Use this feature... If you need to..
Clipboard feature of Export all components or only a subset of components (for

the Broker example, only document types, or only client groups)
Administrator between machines that you know are viewable from the
same Broker Administrator.
For information about copying Broker Server information, see “Copying Broker Server
and Broker Information Using the Import/Export Feature of the Broker Administrator”
below.
For information about copying Broker information from one Broker to another, see
“Deploying Additional Brokers” on page 70.
For information about exporting Broker and Broker Server information for backup
purposes, see “Saving and Restoring System Configuration” on page 74.
For information about the broker_save and broker_load commands, see Appendix A,
“webMethods Broker Command Line Utilities.”
Copying Broker Server and Broker Information Using the Import/Export Feature of
the Broker Administrator
This section describes how to copy Broker Server information using the Import/Export
feature that is available through the Broker Administrator. For a list of other available
methods, see “Methods of Copying Broker Server and Broker Information” above.
Using the using the Import/Export feature, you can export just Broker Server information,
Broker Server and Broker information, or just Broker information.
.
To copy Broker Server information from one Broker Server to another

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 also 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 Broker and Broker Server Configuration Files” on page 57.
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.
To select a subset of any of these options, click Change Selection. By default, document
type, client group, and 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.
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.

Configuring webMethods Broker Servers from the Command Line
File Formats for Broker and Broker Server Configuration

Files
You can save Broker and Broker Server configuration 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.
Configuring webMethods Broker Servers from the Command

Line
You can use the server_config command-line program to create and configure Broker
Servers. You must 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). See Appendix A, “webMethods Broker Command Line Utilities,” for more
information.

Configuring the Storage Cache Size for a webMethods Broker

Server
The Broker Server has a setting in the Broker Server's configuration file for controlling the
storage cache sizes for the storage system, called storage-max-cache-size.
Its value is a number in units of megabytes. The value is ignored if less than 64MB, and the
default value is 128MB. The actual cache size during high load may be slightly higher than
the specified value.
To change the storage cache size
1 Stop the Broker Server. For instructions, see “Stopping and Starting a webMethods
Broker Server” on page 58.
2 Use an editor to open the awbroker.cfg file located in the Broker Server’s data
directory.
3 Add the following line to the awbroker.cfg file:
storage-max-cache-size=nnn
Where nnn is a cache size value. For example, if you wanted to change the cache value
to 256MB, you would enter the following:
storage-max-cache-size=256
4 Save the file.

5 Restart the Broker Server for the new setting to take effect. For instructions, see
“Stopping and Starting a webMethods Broker Server” on page 58.
Note that a larger value will allow a larger cache, which should benefit performance at the
cost of more resource utilization on the host. The cache size should be a value lower than
the available physical memory. Adding more cache space than the available physical
memory may reduce overall performance since the cache will then page to disk. But the
cache size should at least be the size of the log file, since otherwise log operations will
become significantly slower.
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

Stopping and Starting a webMethods Broker Server
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, do one of the following:
Select Leave it Stopped if you want to stop the Broker Server and restart it at a later
time.
Select Restart it Immediately if you want the Broker Server to automatically restart
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 commands 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.
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

Shutting Down the webMethods Broker System
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
commands. See “broker_stop and broker_start” on page 205.
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 2.x
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/S45broker61 stop
This command stops the webMethods Broker processes, awbrokermon and

awbroker.
2 To restart the webMethods Broker processes, enter this command:

/etc/rc3.d/S45broker61 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/S45broker61 stop
This command stops the webMethods Broker processes, awbrokermon and

awbroker.
2 To restart the webMethods Broker processes, enter this command:

/sbin/rc3.d/S45broker61 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Managing Individual Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Deploying Additional Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

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

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 66 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 184.
The following table shows the amount of required swap and memory space for a Broker.
Volatile
Code Documents Guaranteed Documents
Uses System Swap no yes noa
Uses Physical Memoryb yes yes yes
Uses Disk Spacec approx. 5 - 10 MB nod 1900GB max for queue

storage
a.Guaranteed documents use the system’s cache, which is in volatile memory. The limitation
on the size is not contingent on available memory.
b.At least 64MB of physical memory.
c.At least 50MB of disk space.
d.Volatile documents reside in memory. The limitation on the size is the available virtual
memory (physical memory and 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. The
maximum possible performance is gained 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.
Physical memory and swap space. Need to include the needs of other applications on
the same system. webMethods recommends that you also provide a little extra
space to handle unexpected situations.
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.
Important! Pre-5.0 Brokers cannot accommodate guaranteed documents larger than 7MB.
Version 5.0 and 6.0 Brokers will discard guaranteed documents larger than 7MB if
publishing to a pre-5.0 Broker.
To log this action, configure a client on the Broker to subscribe to the document type
Broker::Trace::DropRemote.
See “Understanding Client Group Properties” on page 82 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.
Therefore, any time guaranteed data is added, deleted, or changed, a transaction is
completed. When a guaranteed document is retrieved for deletion, it is not considered a
transaction until the deletion it is acknowledged. Documents are typically acknowledged
when the client requests the next document.
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 34 to learn more about the Broker properties
displayed on the Broker 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 198 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 152).
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 112.
For information about deleting client groups, refer to “Assigning “Can Publish” and “Can
Subscribe” Permissions” on page 88.

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.
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.
Broker commands
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
information about using the broker_save and broker_load commands, see
“webMethods Broker Command Line Utilities” on page 183.
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 commands. In addition, and you have the option of
copying subsets of information. For information about copying Broker Server and
Broker information using the Import/Export feature, see “Copying webMethods
Broker Server and Broker Information” on page 52.
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 about selecting a method, see “Methods of Copying Broker Server
and Broker Information” on page 53.
Copying Broker Information Using the Clipboard Feature of

the Broker Administrator
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 “Copying Broker Server and Broker
Information Using the Import/Export Feature of the Broker Administrator” on page 54 for
more information.

Deploying Additional Brokers
For information about other available methods, see “Methods of Copying Broker Server
and Broker Information” on page 53.
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.
4 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.


CHAPTER 5
Saving and Restoring Data
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Saving and Restoring System Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Backing Up webMethods Broker Server Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

CHAPTER 5 Saving and Restoring Data
Overview
There are measures you can take to protect the webMethods Broker system from loss in
the case of a disk crash or other hardware failure. This chapter describes how to back up
and restore system configuration information and data files.
Saving and Restoring System Configuration

webMethods recommends that you save copies of your webMethods Broker system
configuration and update them whenever you modify the system. The system
configuration for a webMethods Broker system consists of the configuration information
for each Broker Server and Broker.
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.
Saving System Configuration

Backing up the configuration of a single Broker is a simple matter. 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.

Saving and Restoring System Configuration
Sample Backup Configuration
Broker B Broker D
Broker A Broker C
Territory 1 on Broker Server Alpha Territory 2 on Broker Server Beta
To back up the entire system, you must save a separate configuration file for each Broker
and each Broker Server. Therefore, in 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
When webMethods Broker saves configuration files, it uses a file format called the
ActiveWorks Definition Language (ADL). When you name configuration files, you must
save them as .adl files. You can save configuration files from Broker Administrator or
command line.
Note: You should save copies of the Broker and Broker Server configuration files in a
location other than a webMethods Broker host. That way if ever the disks fail on the
Broker Server host, the back up files are still safe.
Saving Broker Server Configurations

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

If you prefer to work from the command line, use the broker_save program to save a
configuration file for each server and each Broker in the configuration. Refer to
“broker_save” on page 203 for instructions.

Restoring System Configuration

You should restore a webMethods Broker system configuration following the order
described in this section. If you want to change the names of Broker Servers, Brokers, or
territories before restoring 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 “File
Formats for Broker and Broker Server Configuration Files” on page 57.
To restore a system configuration
1 Start with clean, newly installed Broker Servers.

As part of the installation process, webMethods Broker creates a Broker Server and a
default Broker. To install multiple Broker Servers on a single host, see “server_config
create” on page 187.
On each Broker Server, create all Brokers that were in the configuration.
If you are using the command-line program broker_load and do not know which
Broker was the default, view the Broker .adl files for the declaration
isDefaultBroker = true.
Create a Broker using these tools:
Tool: Described in:
Broker Administrator “Creating New Brokers” on page 64

broker_create “broker_create” on page 197
program
2 Import the Broker Server configuration files using one of these tools:
Tool: Described in:
Broker Administrator “Copying Broker Information Using the Clipboard

Feature of the Broker Administrator” on page 70
broker_load program “broker_load” on page 200

Backing Up webMethods Broker Server Data
3 Import the Broker configuration files using one of these tools:
Tool: Described in:
Broker Administrator “Copying Broker Information Using the Clipboard Feature

of the Broker Administrator” on page 70
broker_load program “broker_load” on page 200
If the configuration contains any gateways, take note of warnings that indicate that
the other side of the gateway is not yet available.
4 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.
Backing Up webMethods Broker Server Data

It is important that you regularly back up the data on your Broker Server. The files in the
Broker Server’s data directory contain current information about the Broker Server’s
configuration, and about the configuration and statistics for each of the Brokers on the
Broker Server. Together with any SSL certificate files, the data directory is the complete
identity of a Broker Server.
Backing Up webMethods Broker Server Data Files

The simplest way to protect Broker configuration information is to make regular backups
of the data directory for each Broker Server. When you install webMethods Broker, the
data directory for the default Broker Server is located at:
On this
platform: The data files are located here:
Windows C:\Program Files\webMethods6\Broker\data\awbrokers61\default
UNIX /var/opt/webmethods/awbrokers61/default
The Broker Server configuration file awbroker.cfg resides in the Broker Server data
directory and should be backed up regularly. For queue storage sessions, back up
Broker.qs (binary) and any configured queue storage and log files.
Important! Backing up the Broker Server files while there are documents in the Broker
Server is not recommended because documents could be delivered again or could be lost
when the data files are restored.

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 58.
To back up the Broker Server data directory
1 Stop the Broker Server. See “Stopping and Starting a webMethods Broker Server” on
page 58 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\awbrokers61\default\Broker.qs.stor.
3 Restart the Broker Server. See “Stopping and Starting a webMethods Broker Server”
on page 58 for instructions.
Restoring the webMethods Broker Server Configuration

If a Broker Server crash or other system problem causes the loss of the Broker Server data
files, you can restore the Broker Server configuration by copying the files back to the
Broker Server data directory (not recommended for Brokers that are part of a territory).
Note: If there were any guaranteed or persistent documents in the queues when you
made the time the backup files, those documents are resent when you restore the 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 168.

PART III
Client Administration
Managing Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Managing Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Managing Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

CHAPTER 6
Managing Client Groups
Understanding Client Group Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Displaying Client Group Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Creating and Configuring a Client Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Deleting a Client Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

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
lifecycles: Explicit destroy and Destroy on disconnect. See
“Lifecycle Properties” on page 83.
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 83.
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 88.
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 88.
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 90.
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 90.

Understanding Client Group Properties
Lifecycle Properties
The lifecycle 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 lifecycles are shown below.
Lifecycle 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 lifecycle for applications that
need to maintain state information in the Broker between
connections.
For example, a webMethods Broker dbAdapter uses the
explicit destroy lifecycle 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 192.
Persistent Broker versions 5.0 through 6.0 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 192 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
lifecycle 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 lifecycle 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 Lifecycle 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 Lifecycle 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 90.
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 90.

There are four general steps to follow when creating and configuring a client group:
1 Create a client group by assigning a name, lifecycle, and client a queue storage type to
the client group. See “Creating a Client Group” on page 87 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 88 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 162).
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 lifecycle 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 “Lifecycle
Properties” on page 83 for details about client group lifecycle properties.
7 Select the queue storage type (if you selected Explicit Destroy lifecycle) 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 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 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 Broker 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 87.
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
About Managing Document Types in a Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Displaying the Document Types in a Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Editing Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Displaying Subscription Filter Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

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 17. 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 96.
Storage Type The document type’s storage type. See “Document Type
Storage Types” on page 97.
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 97”.

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 98.
Fields The data fields of a document. See “Data Field Information”
on page 99.
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 30
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 83. 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 85.
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Viewing Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Managing Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110
Monitoring Broker Client Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Controlling Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112

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 112.
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 31. 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. none specifies that the events
will be processed in no particular order. The default is
publisher.
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 113.
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 lifecycles, 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 107 for a description of each statistic.
4 Click Clear Client Queue.
5 In the confirmation dialog box, click OK.
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 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.
If you have multiple subscriptions selected at the time you use this command, all of the
selected subscriptions are removed.

Controlling Clients
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 Broker 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
Territories and Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Managing Broker Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

CHAPTER 9
Monitoring and Managing Transactions
Using Transaction Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118
Viewing Running Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118
Setting the Timeout Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119
Manually Performing a Commit or Roll Back . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Viewing and Purging Lost Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

C H A P T E R 9 M o n i t o r i n g a n d M a n a g i n g Tr a n s a c t i o 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:
Started The Broker has received a request to start a transaction and has given a
transaction ID to the client.
Open The transaction is in progress and has not yet been prepared or committed.
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.
Rolled Back 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 pre-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.
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 Transactions.
6 Select the transactions you want to purge and click Destroy.


CHAPTER 10
Territories and Gateways
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Managing Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Territory Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

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. You cannot mix
the two modes.
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)

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 34.
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
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
Broker Administrator.

Territory
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 30.
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.
Territory Information Description
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.
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 34.
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 34.
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)
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 141 or “Creating the Gateway (One Broker)” on page 144 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 165.
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
Gamma Beta
Gamma
Territory 1 Territory 2 Territory 3 Territory 4
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.

Territory Gateways
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 141.
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; this allows you. 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 Broker is active.
Paused The Broker has been paused. When a Broker
is paused, it stops all outbound traffic. The
Broker Administrator shows the name of the
session and Broker client that paused the
Broker.

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 Document
Types 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.
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 142 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 146.
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.
3 Click Pause Gateway to pause activity on the Gateway or Resume Gateway to resume
activity on the Gateway.

Territory Gateways
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

2 Navigate to the Gateway Information page. See “Displaying Gateway Information”
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.
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 43 for instructions.
3 Open the Territory Information page of one of the territory Brokers. See “Viewing
Territory Information” on page 127 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 139.
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.

Territory Gateways
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.
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 127 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 142 to set up the Shared Document
Types list.

Territory Gateways
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 Territory Information page of the territory Broker. See “Viewing Territory
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
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 146.
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.

Territory Gateways
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
&&
And
and
||
Or
or

Type of Operator Operator Description
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Using webMethods Broker with SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Using SSL for Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Using SSL Across Territory Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Creating and Managing SSL Certificate Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Working with Firewalls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

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 168.
For information about how to set up the Broker Server to use SSL, see “Configuring the
webMethods Broker Server for SSL” on page 157.
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
by those for 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. Certificates are
issued by a Certification Authority, a trusted central organization that attests to the
identities of those to whom it issues the certificates.
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.

Security Using Secure Sockets
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 153, 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 a certificate file
containing the Broker Server certificates’ trusted root so the client can validate the Broker
Server’s certificate. 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 “Trusted Roots” on page 151. 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.

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

Using webMethods Broker with SSL
In the Broker Administrator, if you use multi-valued attributes in Distinguished Names

and if you 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 178.

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

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.
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
To control access to a Broker Server, use the Access Control page.

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 Lists
for the webMethods Broker Server” on page 161.
Note: The Broker Administrator forces you to include in the ACL 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 162.
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 lifecycle.
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
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 162.
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 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, and trusted root;
authentication certificate, 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
must be placed 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 168.
2 Configure the Broker Server to enable SSL. This procedure is described in “Enabling
SSL for the webMethods Broker Server” on page 160.
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 158
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 158.
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 158.
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 158.
4 Using the Broker Administrator, enable SSL for the Broker Server.
See “Enabling SSL for the webMethods Broker Server” on page 160.
5 If required, set up an ACL to control administrative access to the Broker Server.
See “Setting Up Access Lists for the webMethods Broker Server” on page 161.
6 If required, set up ACLs to control administrative access to Brokers.
See “Setting Up Client Group Access Control Lists” on page 162.

Determining If You Have an SSL License Key

To configure the Broker Server to support SSL, you must first have a runtime 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 32.
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 Lists for the webMethods
Broker Server” on page 161.
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 158.
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 168 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 156.
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.
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.
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 158 for instructions.
2 Once the Identity Settings are established on the Broker Administrator, open the
webMethods Broker Server Information page for the Broker Server.
3 From the webMethods 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 Lists for the
webMethods Broker Server” on page 161 for instructions.

Setting Up Access 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 154. 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 158.
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 32.
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 168.
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 168.
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.
To set up Client Group access control lists, follow these steps:
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 160 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.

Using SSL for Territories
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 168.
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.
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 168.
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.
Access to a territory is controlled by an Access Control List. To set up SSL for a territory, follow these
steps:
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 157.
2 Open the Territory Information page of one of the Brokers in the territory. See “Viewing
Territory Information” on page 127 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 160 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.

Using SSL Across Territory Gateways
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.

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.

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 43.
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 157.
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 141.
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
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 163.
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 168.
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 144.
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 166.
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.
Creating and Managing SSL Certificate Files

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 170.
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 171.
list-trust Lists the trusted roots in a certificate file. See “Listing Trusted
Roots” on page 174.
remove-trust Removes a trusted root from a certificate file. See “Removing
Trusted Roots” on page 174.
For Certificates and Certificate Files
certify Installs signed certificates into a certificate file. See “Installing
Certificates” on page 173.
copy Copies certificates and certificate files. See the following sections:
“Copying All Certificates in a Certificate File” on page 176.
“Exporting a Single Certificate” on page 176.
“Changing Certificate Files to an Exportable Format” on

page 177.
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 175.
make-new Creates a new key pair and a certificate request. See “Generating
Key Pairs and Certificate Requests” on page 171.

Subcommand Purpose
password Changes the password for a certificate file. See “Changing the
Certificate File Password” on page 178.
remove Removes a certificate from a certificate file. See “Removing
Certificates from a Certificate File” on page 177.
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 174.
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 175.

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 178.
-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
-----BEGIN NEW CERTIFICATE REQUEST-----
[Text deleted]
-----END NEW CERTIFICATE REQUEST-----
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

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 171).
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.
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
1. International Telecommunication Union recommendations are available through subscription.

See http://www.itu.ch.

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 171), 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.

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

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 171), 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.
marks, as described in “Using Distinguished
Names with awcert” on page 178.
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
-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 175.
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

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 152, 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’

Working with Firewalls
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
UNKNOWN typically 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 158.
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.


PART V
Reference
webMethods Broker Command Line Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Tips and Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

APPENDIX A
webMethods Broker Command Line Utilities
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
server_config add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
server_config create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
server_config delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
server_config help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
server_config list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
server_config remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
server_config start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
server_config stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
server_config storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
server_config update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
broker_buildall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
broker_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
broker_delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
broker_load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
broker_ping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
broker_save . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
broker_stop and broker_start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
broker_status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

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.exe 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 186
new one.
create Create a new Broker Server. 187
delete Delete a Broker Server including all its data 189
files.
help Display help commands. 190
list List known Broker Servers. 190
remove Remove a Broker Server but retains all its 190
data files.
start Start a specified Broker Server. 191
stop Stop a specified Broker Server. 191
storage Configure queue storage sessions for a 192
specified Broker Server.
update Update an existing Broker Server. 195
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\awbrokers61\default
UNIX /var/opt/webmethods6/awbrokers61/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 5.x or earlier,
please refer to the documentation for that version of the product.
Broker Commands
Broker commands are shown in the table below:
Command Description Page

broker_buildall Compiles all intelligent integration components and 196
scripted operations on a Broker.
broker_create Creates a new Broker. 197
broker_delete Deletes a Broker. 198
broker_load Imports Broker data from a file to a Broker. 200
broker_ping Sends system ping documents through a Broker. 201
broker_start Starts the Broker Server. 205
broker_stop Stops all Brokers running on the Broker Server, halts 205
all document delivery, and disconnects all clients.
broker_status Displays statistics from the command line for a 207
specific Broker.

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.exe add data_dir <-e executable -k license_key |
-m config_file> [-k license_key] [-p port] [-S]
Arguments
Argument Description
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.
-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 runtime license key. This license key overrides
any existing license key.
-S Silent operation. No output is shown except for warnings and
error messages.

server_config create
Examples
The following example adds a new Broker Server (placing a configuration file in the
newserver 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\awbrokers61\newserver” -m “C:\Program
Files\webmethods6\Broker\data\awbrokers61\server2” -p 6830
The following example adds an existing Broker Server to the active configuration. The
configuration file already exists in the oldserver directory.
server_config.exe add “C:\Program
Files\webmethods6\Broker\data\awbrokers61\oldserver”
server_config create
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 a configuration file, awbroker.cfg, and the data files used by individual Brokers
(described in “Backing Up webMethods Broker Server Data” on page 77) and places them
in the data directory data_dir, as specified in the command.
Syntax
server_config.exe create data_dir -k license_key [-d description] [-p port]
[-nostart] [-S] -session_config sc-type
-session_data sc-type [-qs_log_file filename file-size][ -
qs_storage_file filename file-size [reserved-size]]
Arguments
data_dir The path to the data directory for the Broker Server being
created. If the directory does not already exist, the
program creates it. The directory cannot contain a copy of
the awbroker.cfg file.
Use double quotes if there is spacing in the data directory
path.
-k license_key The Broker Server runtime license key (required).
-d description A short description of the Broker Server, which appears
in the Broker Administrator main window. If the text
string includes spaces, enclose it in quotation marks.

-p port The port number to be used for the new Broker Server.
Needed if another Broker Server is using the default port
6849.
-nostart Creates the Broker Server, but the Broker Monitor process
will not start the Broker Server.
-S Silent operation. No output is shown except for warnings
and error messages.
-session_config sc-type sc-type is the value of a session If you do not specify
session_data it is set to the value of session_config.
You can select the session configuration type when you
create a Broker Server. You cannot change it afterwards.
The default is: -session_config qs
-session_data sc-type sc-type is the value of a session If you do not specify
session_data it is set to the value of session_config.
You can select the session configuration type when you
create a Broker Server. You cannot change it afterwards.
The default is: -session_data qs
-qs_log_file file-size specifies the amount of storage space allowed.
filename file-size Follow the amount with K, M, or G for kilobytes,
megabytes and gigabytes of storage.
You can resize the log file by increasing or decreasing the
value of file-size.
The default is:
-qs_log_file <datadir>/Broker.qs.log 32M
-qs_storage_file file-size specifies the amount of storage space allowed.
filename file-size Follow the amount with K, M, or G for kilobytes,
[reserved-size] megabytes and gigabytes of storage.
You can resize the storage file by increasing the value of
file-size; however, you cannot decrease the size of the
storage file.
reserved size specifies the amount of storage that should
be reserved until runtime. Anticipate a small delay in
operation while clearing takes place.
The default is:
-qs_storage_file <datadir>/Broker.qs.stor 512M
64M

server_config delete
Example
The following example creates a new Broker Server using port number 6840. The required
license key is abbreviated for brevity. The example uses the default storage parameters.
server_config.exe create “C:\Program
Files\webmethods6\Broker\data\awbrokers61\server2” -k BKR-XXXX -p 6840
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 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.exe delete data_dir [-f] [-S]
Arguments
data_dir The path to the data directory for the Broker Server you are deleting.
-f Forces deletion of the Broker Server without requesting confirmation.
If the Broker Server is running, server_config attempts to stop it.
-S Silent operation. No output is shown except for warnings and error
messages.
Example
The following example deletes a Broker Server.
server_config.exe delete “C:\Program
Files\webmethods6\Broker\data\awbrokers61\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.exe
help followed by the subcommand.
Syntax
server_config.exe help
Example
The following example returns a description, including variables and notes, for the add
subcommand:
server_config.exe 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.exe 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.exe list -h atlas
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

server_config start
prompted to continue. Before you remove the Broker Server, make sure the Broker Server
is not running.
Syntax
server_config.exe remove [-f] [-S]
Example
The following example removes a Broker Server.
server_config.exe remove “C:\Program
Files\webmethods6\Broker\data\awbrokers61\server2”
server_config start
The server_config start command starts the Broker Server.
Syntax
server_config.exe 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 205.
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.exe 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 205.
server_config storage
The storage subcommand configures storage sessions for a specified Broker Server.
Upon installation of a Broker Server the user will have created two separate data files: a
log file, into which data is first written before being stored in the second file, a storage file.
By default, each Broker Server has only one log file of up to 1GB with a transaction size of
1GB, and a storage file that can be increased to a maximum size of 32GB by using the
server_config storage command. For details regarding log file size, see “Maximum
Storage File Size” on page 84.
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.
When configuring storage sessions for a Broker Server, it is important to note that the
storage cache size should be at least as large as the storage log file. Otherwise, the Broker
performance for durable events will be reduced. See “Configuring the Storage Cache Size
for a webMethods Broker Server” on page 194 for information and instructions on
configuring a Broker Server’s storage cache size.
Note: You must stop the Broker Server before configuring additional storage files.
Syntax
storage datadir
[ -qs_log_file filename file-size ]
[ -qs_storage_file filename file-size [reserved-size]]*
Arguments
data_dir The path to the data directory for the Broker Server to which you
are adding storage files.

server_config storage
-qs_log_file
filename Name of the log file.

file-size File-size specifies the amount of storage space allowed. Follow the
amount with K, M, or G for kilobytes, megabytes and gigabytes of
storage.
The default is:
-qs_log_file <datadir>/Broker.qs.log 32M
Note: For qs sessions, you can configure a single log file, and
multiple storage files, that is, -qs_storage_file can appear
multiple times.
When configuring storage sessions for a Broker Server, note that

creating a very large log file can impact the Server’s startup time.
For example, a Broker Server with an 8GB log file could take as
much as 30 minutes to start up, depending on hardware.
The storage cache must be at least as large as the log; otherwise,

the Broker Server performance for durable events will be
reduced. For more information, see “Configuring the Storage
Cache Size for a webMethods Broker Server” on page 194.
-
qs_storage_file
filename Name of the storage file.
file-size file-size specifies the amount of storage space allowed.
[reserved-size] Follow the amount with K, M, or G for kilobytes, megabytes and

gigabytes of storage.
reserved size specifies the amount of storage that should be
reserved until runtime. Anticipate a small delay in operation
while clearing takes place.
The default is:
-qs_storage_file datadir/Broker.qs.stor
512M 64M
Note: For qs sessions, you can configure a single log file and
multiple storage files, that is, -qs_storage_file can appear multiple
times.

Example
The following example creates an additional storage file for a Broker Server:
server_config.exe storage “C:\Program
Files\webmethods6\Broker\data\awbrokers61\default” -qs_storage_file
“C:\Program Files\webmethods6\Broker\data\awbrokers61\default\
MoreStorage.qs.stor” 1024M 128M
Configuring the Storage Cache Size for a webMethods

Broker Server
The Broker Server has a setting in the Broker Server's configuration file for controlling the
storage cache sizes for the storage system, called storage-max-cache-size.
Its value is a number in units of megabytes. The value is ignored if less than 64MB, and the
default value is 128MB. The actual cache size during high load may be up to 115% of the
specified value.
To change the storage cache size
1 Stop the Broker Server. For instructions, see “broker_stop and broker_start” on
page 205.
2 Use an editor to open the awbroker.cfg file located in the Broker Server’s data
directory.
3 Add the following line to the awbroker.cfg file:
storage-max-cache-size=nnn
Where nnn is a cache size value. For example, if you wanted to change the cache value
to 256MB, you would enter the following:
storage-max-cache-size=256
4 Save the file.

5 Restart the Broker Server for the new setting to take effect. For instructions, see
“broker_stop and broker_start” on page 205.
Note that a larger value will allow a larger cache, which should benefit performance at the
cost of more resource utilization on the host. The cache size should be a value lower than
the available physical memory. Adding more cache space than the available physical
memory may reduce overall performance since the cache will then page to disk. But the
cache size should at least be the size of the log file, since otherwise log operations will
become significantly slower.

server_config update
server_config update
You can update the following configuration information for an existing Broker Server:
Runtime license key
Port number of the server. .
Note: 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.exe 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.
-k license_key The new runtime 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.

Example
The following example updates the configuration of a Broker to use a new runtime license
key. The required license key is abbreviated here.
server_config.exe update “C:\Program
Files\webmethods6\Broker\data\awbrokers61\server2” -k BKR-XXXX
broker_buildall
Use the broker_buildall command line utility to compile all intelligent integration
components and scripted operations from a Broker. This command line utility is
particularly useful when used in conjunction with broker_load to migrate a Broker
configuration from your webMethods Broker test environment to your production
environment.
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.

broker_create
[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 153. To gain administrative access, use the following ID
options with the broker_status 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.

-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 153.
To gain administrative access, use the following ID options with the
broker_stop 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]

broker_delete
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.
filename
certificate file.

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.

broker_ping
Lists (ACLs).
-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
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 arguments to broker_ping are defined as:

-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/] Pings broker2 remotely through the Broker. See
broker2 “Pinging a Remote Broker” on page 202.
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 153. 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

broker_save
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 130.
broker_save
Use the broker_save program from the command line to save Broker configuration
information for a specified Broker to a file.
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 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 153. To gain administrative access, use the following ID options
with the broker_status 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

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

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
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 206.
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.
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
Broker Server, as described in “Access Control Lists” on page 153.
To gain administrative access, use the following ID options with
the broker_stop command:
filename

certificate file.
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 2.x
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/S45broker60 stop
This command stops the webMethods Broker processes, awbrokermon and awbroker.
To restart the webMethods Broker processes, enter this command:
/etc/rc3.d/S45broker60 start

broker_status
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/S45broker60 stop
This command stops the webMethods Broker processes, awbrokermon and awbroker.
To restart the webMethods Broker processes, enter this command:
/sbin/rc3.d/S45broker60 start
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
Lists (ACLs).
filename

certificate file.
[broker@]server[:p The name of the webMethods Broker (and optionally, the Broker
ort] 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
webMethods Broker Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

A P P E N D I X B T i p s a n d Tr o u b l e s h o o t i n g
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 203.
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 200.
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 43 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 83 and “Maximum Storage File Size” on
page 84.
Client Group A document with an explicit destroy lifecycle remains in a

lifecycle client queue until the receiving client pulls it from the queue.
See “Lifecycle Properties” on page 83.
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 211.

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 46.
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 214). 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

The following table lists and describes Broker Server error messages. They are listed in
numerical order.
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.
Msg
No. Error Message Explanation
1000 webMethods Broker ready, process Informational.
id number
1001 webMethods Broker exiting, process Informational.
id number
1002 Could not start Windows sockets: Check the network configuration.
system error
1003 Wrong version of Windows sockets Unsupported version of Windows.
1004 Could not get local host name: system Check the network configuration.
error — Check network
configuration.
1005 Cannot open guaranteed data store: A fatal error has occurred. Data store
system error files are not accessible.
1006 Cannot open persistent data store: This error message is no longer issued
system error by the Broker Server.
1007 Cannot allocate guaranteed storage: This error message is no longer issued
1008 Data store wrong version Data files cannot be used from one
version of the product to the next.
1009 - Starting adapter process... These error messages were adapter-
related and are no longer issued by
1020
the Broker Server.
1021 Cannot accept connections: system Check the network configuration.
error
1022 Cannot create main socket for Check the network configuration.
network connections: system error

Msg
1023 Cannot bind main socket to port Software was installed more than
number: system error — Another once.
webMethods Broker may be running
already
1024 Cannot create thread: system error — This error message is no longer issued
[EXITING] by the Broker Server.
1025 webMethods Broker Monitor ready, Informational.
process id number
1026 webMethods Broker Monitor This error message is no longer issued
exiting, process id number by the Broker Server.
1027 Cannot open config file file name: UNIX only. Missing configuration file.
system error — The webMethods Call webMethods Technical Services.
Broker Monitor must be started in
the top install directory
1028 Incomplete config file file name This error message is no longer issued
by the Broker Server.
1029 Restarted webMethods Broker file x UNIX only. Problem starting Broker
times, giving up Server. Look for other error message.
1030 Starting webMethods Broker file — UNIX only. Install problem.
cannot create process: system error
1031 Stopping webMethods Broker file This error message is no longer issued
pid number — cannot terminate by the Broker Server.
process: system error
1032 Stopping webMethods Broker Install problem.
directory pid number - cannot get
exit code: system error
1033 Unexpected stop of webMethods Broker Server runtime error. Call
Broker file pid number — exit code webMethods Technical Services.
number
1034 Unexpected stop of webMethods UNIX only. Install problem.
Broker file pid number — Signal x and
system error
1035 - webMethods Broker directory pid These error messages are no longer
number... issued by the Broker Server.
1036
1037 Wait on synchronization object An internal error has occurred. Call
failed: system error webMethods Technical Services.

Msg
1038 Starting webMethods Broker file Informational.
1039 Stopping webMethods Broker file Informational.
pid number
1040 Cannot get address for local host This error message is no longer issued
name: system error by the Broker Server.
1041 Cannot create socket for SNMP: This error message is no longer issued
system error — SNMP traps will not by the Broker Server.
be sent
1042 Cannot bind SNMP socket to port: This error message is no longer issued
system error — SNMP traps will not by the Broker Server.
be sent
1043 Starting webMethods Broker — UNIX only. Something is wrong with
could not find executable file: system the install.
error
cannot create pipe: system error the install.
1045 Starting webMethods Broker — file is UNIX only. Something is wrong with
not executable the install.
cannot find directory: system error the install.
directory is not a directory the install.
1048 Parsing filter n — y This error message is no longer issued
1049 webMethods Broker cannot get IP This error message is no longer issued
address for itself x: by the Broker Server.
1050 Multiple attempts to open data store. This error message is no longer issued
1051 Insufficient memory resources for Out of memory.
operation
1052 - Storage-related messages from pre- These error messages are no longer
1084 5.0 Servers. issued by the Broker Server.
1085 %1 This error message entry is no longer
issued by the Broker Server.
1086 %1: %2 This error message entry is no longer
issued by the Broker Server.

Msg
1087 Cannot start service dispatcher: Internal error for Windows Systems
system error only.
1088 Object system error: system error This error message is no longer issued
1089 Cannot register service service name: Internal error for Windows Systems
system error only.
1090 Cannot access registry key key: This error message is no longer issued
1091 Cannot access directory directory: This error message is no longer issued
1092 Cannot set environment variable This error message is no longer issued
variable: system error by the Broker Server.
1093 Cannot set service status: system error Internal error for Windows Systems
only.
1094 Attempted to start webMethods This error message is no longer issued
Broker before starting webMethods by the Broker Server.
Broker Monitor.
1095 Attempted to stop webMethods This error message is no longer issued
Broker before starting webMethods by the Broker Server.
Broker Monitor.
1096 Cannot open service control Internal error for Windows Systems
manager: system error only.
1097 Cannot create service service name: Internal error for Windows Systems
system error only.
1098 Cannot open service service name: Internal error for Windows Systems
system error only.
1099 Cannot delete service service name: Internal error for Windows Systems
system error only.
1100 Cannot start service service name: Internal error for Windows Systems
system error only.
1101 Cannot stop service service name: Internal error for Windows Systems
system error only.
1102 The license key is missing for Install problem.
webMethods Broker. The software
will not run without a license key

Msg
1103 The license key x is invalid. The Incorrectly typed key.
webMethods Broker will not run
without a valid license key
1104 The license key has expired for the Expired license key Call webMethods
webMethods Broker. The Broker will Technical Services.
not accept any documents until the
license is updated
1105 Broker initialization failed, network An internal error has occurred during
manager did not start — system error start up. Call webMethods Technical
Services.
1106 Broker initialization failed, network This error message is no longer issued
listener did not start — system error by the Broker Server.
1107 Internal error — system error An internal error has occurred. Call
webMethods Technical Services.
1108 Broker initialization failed, cannot An internal error has occurred during
create IO port — system error start up. Call webMethods Technical
Services.
1109 Client connection failed, cannot use An internal error has occurred. Call
IO port — system error webMethods Technical Services.
1110 Persistent data file file name is This error message is no longer issued
missing, resetting brokers and client by the Broker Server.
queues.
1111 Found persistent storage file, but no This error message is no longer issued
guaranteed storage file. Expected to by the Broker Server.
find file file name.
1112 Reached operating system The process or computer cannot
connection limit. No more support any more connections. See
connections can be made to the your system documentation about
webMethods Broker until existing increasing the connection limit or
connections are closed resources.
1113 Network I/O operation x failed — Unexpected I/O failure, connection
system error closed. The computer may be running
low on memory.
1114 Wrong password for SSL key file file You have provided an incorrect
name. SSL disabled. password for the SSL certificate file.
1115 Could not find SSL key file file name. The specified SSL certificate file does
SSL disabled. not exist.

Msg
1116 Error in SSL key file file name, error The certificate file has an invalid entry
code x. SSL disabled. or is corrupted. Make sure you have a
valid certificate file.
1117 Error in SSL library error code. Could This error message is no longer issued
not find symbols symbol name — SSL by the Broker Server.
disabled.
1118 Could not create SSL socket, error An internal error has occurred. Call
code x. SSL disabled. webMethods Technical Services.
1119 Could not accept SSL connection, There is an error on the client side of
error code x the connection.
1120 Could not accept SSL connection, There is an error on the client side of
bad handshake from address:port. the connection.
1121 Fatal error, SSL disabled: error_code1 An internal error has occurred. Call
error_code2 webMethods Technical Services.
1122 Could not find DN <Distinguished The certificate file does not contain the
Name> in key file file name. SSL specified Distinguished Name. Make
disabled. sure you have a valid certificate file.
1123 SSL connection using expired The specified certificate belonging to
certificate the client has expired. Get a valid
DN = <Distinguished Name> certificate from your Certificate
begin-date = date Authority.
end-date = date
1124 webMethods Broker SSL certificate The specified certificate used by the
has expired. Clients using SSL may Broker Server has expired. Get a valid
refuse to connect to webMethods certificate from your Certificate
Broker until the certificate is Authority.
renewed.
DN = <Distinguished Name>
begin-date = date
end-date = date
1125 No certificate for DN <Distinguished The certificate file does not contain the
Name> in key file file name. SSL specified Distinguished Name. Make
disabled. sure you have a valid certificate file.
1126 Incomplete configuration, the Broker This error message is no longer issued
cannot be started. This is usually by the Broker Server.
caused by an error during
installation.

Msg
1127 webMethods Broker server failed on See the system log for more errors.
first start, giving up.
1128 Out of memory while sending data A low memory condition exists on the
to IP network address address, host.
connection has been broken
1129 - Persistent data file file name is... These error messages are no longer
1134 issued by the Broker Server.
1135 The statistics for Broker have been This error message is no longer issued
reset. by the Broker Server.
1136 The incoming queue for Broker has This error message is no longer issued
been reset, all unprocessed persistent by the Broker Server.
documents have been lost.
1137 The statistics for document type This error message is no longer issued
document type on Broker have been by the Broker Server.
reset.
1138 The statistics for client group Client This error message is no longer issued
Group on Broker have been reset. by the Broker Server.
1139 The statistics for client client on This error message is no longer issued
Broker have been reset. by the Broker Server.
1140 The queue for client client on Broker This error message is no longer issued
has been reset, all unfetched by the Broker Server.
persistent documents have been lost.
1141 Could not determine Fully Qualify The Broker Server cannot determine
Name for computer, using host. this host’s complete name; the domain
Some clients Broker or Brokers may part is missing. This error usually
not be able to contact this Broker. indicates a problem with the host’s
name service configuration. Brokers
may be unable to communicate with
other Brokers or clients, especially
those in other domains.
1142 Close to maximum storage limit on This error message is no longer issued
data store file — xK bytes available, by the Broker Server.
yK bytes maximum
1143 Maximum storage limit reached for This error message is no longer issued
data store file — xK bytes available, by the Broker Server.
yK bytes maximum

Msg
1144 Resolved low storage space for data This error message is no longer issued
store file — xK bytes available, yK by the Broker Server.
bytes maximum
1145 The statistics for remote Broker This error message is no longer issued
remote Broker on Broker have been by the Broker Server.
reset.
1146 The forward queue for remote This error message is no longer issued
Broker remote Broker on Broker has by the Broker Server.
been reset, all unprocessed persistent
documents have been lost.
1147 Warning: could not write The Broker Server Monitor service
webMethods Broker configuration could not write the awbroker.cfg file
file. to the directory.
1148 Could not read webMethods Broker The Broker Server Monitor service
configuration file file name from could not find the Broker Server
directory directory: error code configuration file at the specified
location.
1149 Incomplete webMethods Broker The Broker Server configuration file is
configuration file file name from corrupted.
directory directory [EXITING]
1150 Could not read new webMethods The Broker Server Monitor service
Broker configuration file in directory could not find the Broker Server
directory configuration file at the specified
location.
1151 Could not read webMethods Broker The Broker Server Monitor service
configuration file in directory could not find the webMethods
directory. Broker configuration file at the
specified location.
1152 Could not query webMethods An internal error has occurred on a
Broker as service service name: system Windows System.
error.
The Broker Server Monitor cannot
query the Broker Server service.
1153 webMethods Broker Monitor found Informational message
new webMethods Broker with data
directory in directory.

Msg
1154 webMethods Broker Monitor found Informational message
webMethods Broker with data
directory in directory, already
known.
1155 webMethods Broker Monitor Informational message.
reading configuration from file file
name.
1156 Received an error label reply from An access label adapter failed to
access label adapter ALA_name: assign an access label for the specified
Error: error_code client.
Detail: error_text
Client DN: Distinguished Name
Client Issuer DN: Distinguished Name
1157 Received a label reply for an An access label adapter has returned
unknown client from access label an access label when the Broker was
adapter ALA_name: not expecting one.
Client DN: Distinguished Name
Client Issuer DN: Distinguished Name
1158 Error: Could not find access label The access label adapter for this
adapter client. Access label lookup Broker is not running.
not available.
1159 Received reply containing an illegal The access label adapter has issued an
label from access label adapter access label that has an invalid form.
ALA_name
1160 Error: Could not allocate memory to A low memory condition exists on the
send lookup to access label adapter. host.
Access label lookup not available.
1161 Error: Could not prepare lookup An internal error has occurred.
document to send to access label
adapter. Access label lookup not
available.
1162 Error: Could not create SSL socket: The Broker Server has not been
SSL not initialized. SSL disabled. configured for SSL support.
1163 Error: Could not create SSL socket The Broker Server cannot open the
for port port number: could not open SSL sockets used to accept client
socket (system error). SSL disabled. connections.
1164 Error: Could not create SSL socket A low memory condition exists on the
for port port number: no memory. SSL host.
disabled.

Msg
1165 Error: Could not create SSL socket: Another application may be using the
bind to port port number failed (error port.
code). SSL disabled.
1166 Error: Could not create SSL socket: An unusual error condition has
listen on port port number failed occurred. Contact webMethods
(error code). SSL disabled. Technical Services and supply the text
of the log message.
1167 Warning: Could not resolve The hostname specified in
specified webMethods Broker awbroker.cfg could not be found.
hostname hostname to an IP address. The Broker-to-Broker feature may not
Connections from remote Brokers work.
may fail.
1168 SSL key file Key file seems to be Replace the server's certificate file.
corrupted. SSL disabled.
1169 Error: Cannot setuid to user name The user or group cannot be set for the
(uid uid): system error Broker Server Monitor. Check that
user bin and group bin exist on the
local system. If the user and group ids
are specified in awbroker.cfg, check
that they exist on the local system.
1170 Error: Cannot lookup user user or The user or group cannot be found for
group group. the Broker Server Monitor. Check that
user bin and group bin exist on the
local system. If the user and group ids
are specified in awbroker.cfg, check
that they exist on the local system.
1171 Error: Cannot make secure Broker One or more of the Brokers is
connections: SSL is disabled or not configured to use SSL in a territory,
configured. but the Broker Server SSL
configuration is missing or not
working.
1172 Broker: Cannot connect to The local name service configuration
webMethods Broker server, error in is incorrect, or the hostname is
resolving hostname to IP address: missing from the name service tables.
error code Contact local system administration to
fix the problem.
1173 Broker: Cannot connect to It is likely that the Broker Server is not
webMethods Broker server: error code. running on the remote host.

Msg
1174 Broker: Connection to broker@server All Broker Servers in a territory need
was rejected by the remote broker. to include the Broker-to-Broker option
Reason: The remote Broker is not in their runtime license keys. Contact
licensed for territories. webMethods Technical Services.
1175 Broker: Connection to broker@server All Broker Servers in a territory must
was rejected by the remote broker. be compatible with the version of the
Reason: The remote webMethods webMethods Broker system.
Broker is incompatible with this
webMethods Broker.
1176 Broker: Connection to broker@server The remote Broker was removed from
was rejected by the remote broker. the territory but the local Broker has
Reason: The remote Broker does not not been updated about the removal.
have a territory set. This can be caused by poor
connectivity between Brokers in the
territory, or by forced removal of a
Broker using Broker Administrator.
This problem can be fixed by joining
the remote Broker to the territory, or
force removing it from the remaining
Brokers in the territory.
1177 Broker: Connection to broker@server See the explanation for error 1176.
was rejected by the remote broker.
Reason: The remote Broker is not
part of territory territory.

Msg
1178 Broker: Connection to broker@server Territory security has been enabled
was rejected by the remote broker. and the local Broker does not meet the
Reason: Permission denied. permission requirements of the
remote Broker. This error can be
caused by an incorrect certificate DN
on the local Broker Server or
differences in encryption strength (for
example, if US Domestic encryption is
required by the territory but the local
Broker Server only supports US
Export).
This error might occur if the territory
security configuration is out of sync
among the Brokers in the territory.
Export the Broker configuration from
the local and remote Broker, and
compare them for inconsistencies.
Modify the exported ADL files to fix
any problems and import them to the
Broker using the broker_load
command-line program.
1179 Broker: Connection to broker@server Two Brokers have been configured as
was rejected by the remote broker. gateways to the remote Broker. Only
Reason: A gateway to territory one Broker in a territory can provide a
territory already exists on the remote gateway to a given remote territory.
broker.
1180 Broker: Connection to broker@server An unusual error condition has
was rejected by the remote broker. occurred. Contact webMethods
Reason: An internal error occurred Technical Services and supply the text
(error code x). of the log message.
1181 Broker: Cannot connect to An unusual error condition has
broker@server: Received a malformed occurred. Contact webMethods
reply from remote broker. Technical Services and supply the text
of the log message.
1182 Broker: Incorrect Broker connection An unusual error condition has
made to broker@server: configurations occurred. Contact webMethods
are not consistent. Technical Services and supply the text
of the log message.

Msg
1183 Broker: Cannot connect to An unusual error condition has
broker@server: The logical clock is not occurred. Contact webMethods
consistent with the local copy. Technical Services and supply the text
of the log message.
1184 Broker: Initial synchronization failed An unusual error condition has
for Broker connection to occurred. Contact webMethods
broker@server. Technical Services and supply the text
of the log message.
1185 Broker: A Broker connection from See the explanation for error 1178.
broker@server was denied access.
1186 Broker: A gateway connection from See the explanation for error 1178.
broker@server was denied access.
1187 Broker: A Broker connection to This message is issued after a territory
broker@server was successfully connection has been fixed.
established.
1188 Cannot lock data file file name: error This error message is no longer issued
1189 The persistent data file file name is The persistent data file Broker-pers
corrupted beyond repair and has been damaged and the automatic
automatic recovery is disabled. deletion option is disabled. The
[EXITING] Broker Server will not start until the
file is fixed or deleted.
1190 Error: Cannot open the internal log This error message is no longer issued
file file name: system error by the Broker Server.
Internal logging is disabled.
1191 Thread creation failed: system error Internal fatal error. The Broker Server
has run out of resources.
1192 Multiple servers (number of servers) Internal error for HP systems; only
not supported on this platform. one Broker Server supported at a time.
Only starting the first configured See the Release Notes in the HP/UX
server. section for instructions on how to
support multiple servers.
1193 Maximum transaction size exceeded. This error message is no longer issued
1194 Could not accept SSL connection, A client connecting with SSL timed
handshake from IP address: port out.
number timed out after x ms.

Msg
1195 - Error message 1195 - 1221 These error messages are used for
1221 internal purposed only. They are
never issued by the Broker Server.
1222 Check sum failed replaying the This error message is no longer issued
Guaranteed storage log. Broker by the Broker Server.
server cannot continue.
[CRASHING].
1223 Check sum failed processing a A fatal error has occurred. The storage
document (queue type name). Broker file has been corrupted.
server cannot continue.
C queue = client queue
[CRASHING].
F queue = forward queue
1228 The Server has no sessions No valid Broker sessions are
configured. [EXITING]. configured.
1229 The Server cannot initialize config The Server could not create the config
session with URL data_session_URL. session at the data_session_URL.
Error code error code. [EXITING]. Ensure QS files are available, files
could be corrupted or missing.
1230 The Server cannot initialize data The Server could not create the data
session with URL data_session_URL. session at the data_session_URL.
Error code error code. [EXITING]. Ensure QS files are available, files
1231 The Server cannot access it’s Ensure the Server’s configuration files
configuration from the config are available, files could be corrupted
session: error code [EXITING] or missing.
1232 The Server cannot access it’s Ensure the Server’s confutation files
configuration from the data session: are available, files could be corrupted
error code [EXITING] or missing.
1233 The Server cannot access server The Broker Server does not issue this
config object. error message at this time.
1234 The Server cannot store it’s initial The Broker Server could not update
configuration to the config session: it’s initial configuration of the Broker
error code Server. Ensure the Server’s
configuration files are available, files

Msg
1235 Warning: Broker_name: Event The Broker Server tried to publish a
dropped from forward queue to document larger than 7MB between a
remote Broker_name because it was 5.0 Broker and pre-5.0 Broker.
larger than the receiving Broker’s
Pre-5.0 Brokers cannot accommodate
limit (value bytes).
documents larger than 7MB. Large
incoming documents will be
discarded by the pre-5.0 Broker.


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.

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

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

Glossary
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- If this client life cycle is specified, the Broker will destroy
disconnect 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
a body, which contains data fields with values
an envelope, which contains envelope fields (See also,
document envelope.)

Glossary
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. Document Folders are stored in the
Broker.
document tag 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.

Glossary
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.
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.
The Broker Server requires you to open port 6849 on
your firewall for non-SSL connections. 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.
guaranteed storage See storage type.
Java client classes The Java client library that is part of the webMethods
Broker API: Java Edition.

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

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

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

Glossary
volatile storage See storage type.

webMethods Broker webMethods Broker integrates every information
resource allowing access across corporate intranets or
the Internet.
webMethods A webMethods Enterprise adapter with its resource.
Enterprise resource

Index
Index
A gateway 130
Access Control List, see ACL guaranteed storage 68
ACL higher performance 66
Broker 161, 162 managing document types in 94
client group 162 max document types 17
territories 163 maximum number of clients 214
territory gateways 165 maximum number per territory 214
adapter view remote publish 133
about 27 single and multiple sessions 110
adding SSL 161, 162
Broker to Broker Administrator display 43 Broker activity, logging 48
Can Publish and Can Subscribe permissions 88 Broker Administrator 29, 31
more queue storage 194 administering Broker Servers 42
admin client group 162 Broker clients, managing 102
administrative access to Broker 155 certificate 31
applications, uninstalling 69 changing Broker status 65
arithmetic operators for filters 147 connection settings 30
assigning default status to a Broker 65 deploying additional Brokers 70
awbroker 60 document types, managing 94
awbroker.cfg file 77 identity settings 31
awbrokermon 60 Integration Server 26
awcert command, using Distinguished Names introduction 18
with 178 known servers 29, 31
known territories 29, 31
B logging on 24
navigating in 26
backing up Broker data 77
refreshing main page 29
behavior, Broker client 111
removing Broker Servers from 45
Broker
saving system configuration 75
ACL 162
setting up client groups 81
ACL for 161
setting up permissions 30
adding to Broker Administrator display 43
SSL 31
administrative access to 155
SSL support for 158
assigning default status to 65
starting 24
backing up data 77
starting server 59
creating 64
stopping server 59
data directory 77
Utilization page 46
deleting 68
views 27
deploying additional 70
displaying document scopes and document types 94

Index
Broker client broker_ping command 201

behavior, displaying 111 broker_start command 205
deleting 113 broker_status command 207
lifecycle 83 broker_stop command 205
managing 101, 102 Brokers
name limitations 69 maximum number per Broker Server 213
queue storage properties 85
removing subscriptions 112 C
sessions 110 Can Publish permissions
Broker Server adding 88
adding 186 removing 89
administering 42 Can Subscribe permissions
configuration 20 adding 88
configuration, copy and paste 52 removing 89
creating 187 certificate files
error messages 215 changing to an exportable format 177
installation 20 copying all certificates 176
listing 190 creating and managing 168
maximum number of territories 214 exporting a single certificate 176
name limitations 69 passwords, changing 178
overview 16 certificate requests, generating 171
processes 60 certificates
removing 45 deleting 177
setting up 20 exporting single 176
stopping and starting 58 installing 173
storage cache size 194 listing 175
updating configuration 195 certification authority 150
usage information 46 client filters
usage, monitoring 46 applying 103
Utilization page 46 client group
working with multiple instances 212 ACL 162
Broker Server Host 16 admin 162
Broker Server properties, displaying 32 client lifecycle 82
Broker Server statistics, displaying 32 configuring 87
Broker System Log creating 87
display 51 definition 18
exporting from Broker Administrator 51 deleting 92
purging from Broker Administrator 52 description 91
broker_buildall 196 name limitations 69
broker_config. See server_config properties 82
broker_create command 197 setting up 81
broker_delete command 198 SSL 162
broker_load command 200 client lifecycle 82

Index
client queue storage types 83, 85 D

client queue versus document type storage 85 data directory, Broker 77
client state 17 data field, document type 99
clipboard feature 53 data files, Broker 77
command line utilities 19, 183 default Broker, assigning 65
commands definition 17
awcert 178 deleting
broker_config. See server_config Broker client 113
broker_create 197 Brokers 68
broker_delete 198 certificates 177
broker_load 200 client group 92
broker_ping 201 deploying additional Brokers 70
broker_start 205 destroy on disconnect 83
broker_status 207 displaying subscription filter strings 99
broker_stop 205 Distinguished Names 152
configuration Distinguished Names, using with awcert 178
restoring 76 document folder
configuring description 17
Broker Server for SSL 157 document scope
client group 87 displaying 94
SSL for Broker Administrator 158 document size, maximum 67
territory gateways (both Brokers) 141 document type
territory gateways (one Broker ) 144 data field 99
configuring log options 49 definition 17
connection settings displaying 94
Broker Administrator 30 Force Join 129
conventions used in this document 11 managing 94
copy and paste maximum number 17
Broker Server configuration 52 name limitations 69
copying all certificates 176 storage 83, 85
copying Broker information storage types 97
using clipboard feature 53 Time To Live attribute 97
using Import/Export feature 53 versus client queue storage 85
creating Document Type logging 65, 91
additional storage 194 documentation
Brokers 64 additional 12
client group 87 conventions used 11
territories 126 feedback 12
territory gateway (both Brokers) 141 documents
territory gateway (one Broker) 144 filtering 146
guaranteed 67
volatile 68
DSA standard 150

Index
E H
encryption, public key 150 HP-UX, setting maximum thread limit for 211
error messages, Broker Server 215
Event Log I
Broker Administrator 50 Import/Export feature
explicit destroy 83 for copying Broker information 53
exportable format, changing certificate files to 177 importing
exporting from command line 200
single certificates 176 installing
certificates 173
F trusted roots 171
file Integration Server
awbroker.cfg 77 documentation 26
certificate, creating and managing 168 introduction 18
filter
clients 103 J
filtering documents 146 joining territories 129
filters multiple Brokers 129
arithmetic operators 147
displaying subscription 99
K
filter string rules 147
territory gateway 146 known servers
firewalls Broker Administrator 29, 31
known territories 29, 31
opening port through 179
preventing Gateway disconnection from 141
with SSL 179 L
working with 179 leaving territories 130
Force Join 129 license key for SSL 158
license key, updating 48
G lifecycles
destroy on disconnect 83
gateway, see territory gateways
explicit destroy 83
Gateways
properties of 83
pausing activity on 140
limitations
preventing firewall disconnections 141
max document types on Broker 17
resuming activity on 140
maximum size of document 17
generating certificate requests 171
listing
graph, territory 130
certificates 175
guaranteed documents 67
trusted roots 174
Guaranteed storage 84
localhost 212
Guaranteed storage files 84
Log Ack types 82, 87, 90
log options
configuring 49

Index
Log Publish types 82, 87, 90 client group 82

logging Broker activity 48 lifecycle 83
logging with Integration Server 91 public key encryption 150
publish access 82
M
managing Broker clients 102 R
managing territories 126 removing
maximum document size 67 Broker client subscriptions 112
maximum size for storage files 84 Broker Server 45
maximum thread limit for HP-UX 211 Can Publish and Can Subscribe permissions 89
monitoring Broker Server shared document types 145
usage 46 territory gateways 145
multiple Brokers trusted roots 174
joining territory 129 restoring system configuration 76
multiple instances resuming
of a single Broker Server 212 activity on a Gateway 140
RSA standard 150
N rules for territories 125
name limitations, Broker Server 69 rules, filter strings 147
navigating in Broker Administrator 26
network connection 212 S
saving system configuration data 74
O scalability, webMethods Broker 213
opening port through firewall 179 secure sockets
operators, filter 147 described 150
modes of 151
Secure Sockets Layer, see SSL
P
server view
password, certificate file 178 about 27
pausing server_config
activity on a Gateway 140
add subcommand 186
permissions, Can Publish and Can Subscribe 88, 90 create subcommand 187
permissions, Log Publish types and Log Ack types 90 list subcommand 190
Persistent storage 84, 85
update subcommand 195
Persistent storage files 84 with 4.x or earlier 185
PKCS #10 format 172 Services dialog box, Windows 59
processes
sessions, Broker client 110
awbroker 60 setting up client groups 81
awbrokermon 60 shared document type, removing 145
program code conventions in this document 11
shutting down webMethods Broker 60
properties SNMP traps
Broker Server 32 Broker Administrator 50

Index
SSL storage files

a brief description of 150 Guaranteed 84
Broker 161, 162 Persistent 84
Broker Administrator 158 storage files, maximum size 84
certificate files, creating and managing 168 storage types
client group access 162 client queue 83, 85
configuring Broker Server 157 document type 97
Distinguished Names 152 Guaranteed 84
gateways versus territories 167 Persistent 84
license key 158 Volatile 84
modes of secure Sockets 151 subscribe access 82
public key encryption 150 system configuration data, saving and restoring 74
roadmap for implementing with webMethods Broker 156
saving and restoring configuration 74 T
secure sockets 150 territories
standard 150 ACL 163
territories, within 163 creating 126
territory gateways 165 definition 16
trusted roots 151 Force Join 129
using through firewalls 179 joining 129
using webMethods Broker with 153 leaving 130
standard managing 126
DSA 150 multiple Brokers 129
PKCS #10 172 overview 124
RSA 150 rules for 125
SSL 150 saving and restoring configuration 74
X.509 173 SSL within 163
starting unique names for 126
Broker Administrator 24 territory gateways
Broker Administrator, logging on 24 ACL 165
Broker Server 58 configuration process 131
Broker Server, from Broker Administrator 59 configuring (both Brokers) 141
Broker Server, from Windows Services 59 configuring (one Broker) 144
statistics configuring SSL (both Brokers) 166
Broker Server 32 configuring SSL (one Broker) 167
stopping creating (both Brokers) 141
Broker Server 58 creating (one Broker) 144
Broker Server, from Broker Administrator 59 displaying information about 136
Broker Server, from Windows Services 59 filters 146
storage cache size gateway Broker 130
configuring 194 overview 130

Index
removing 145 V
removing a shared document type 145 volatile documents 68
saving and restoring configuration 74 Volatile storage 84, 85
shared document type list (both Brokers) 142
shared document type list (one Broker) 144
W
SSL 165
territory graph 130 WARNINGS
broker_load program, large files 200
territory view
about 27 import file command, large files 56
Time to Live attribute 97 pre-5.0 Brokers, large files 67
WDL 75
trace events
Broker::Trace::Dropremote 67 webMethods Broker
troubleshooting information 12 Definition Language 75
implementing SSL 156
trusted roots
described 151 scalability 213
installing 171 system, shutting down 60
upgrading 42
listing 174
removing 174 using SSL with 153
TTL 97 webMethods Broker Administrator, see Broker Administrator 18
Windows
typographical conventions in this document 11
Event Log, Broker Administrator 50
Services dialog box 59
U
Windows Services
uninstalling applications 69 starting server 59
unique names for territories 126 stopping server 59
updating Broker Administrator 29 working without 212
updating the license key 48
upgrading
X
webMethods Broker 42
X.509 digital certificate 173
usage, Broker Server 46
Utility Logger 65
logging with Integration Server 91
Utilization page
Broker Administrator 46

Index

Broker Admin Guide

Uploaded by

Document Information

Original Description:

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-61-20040116

About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Part I. Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Chapter 1. Overview of webMethods Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

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

webMethods Broker Administrator’s Guide Version 6.1 3

Displaying Broker Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Part II. Broker Server and Broker Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Chapter 3. Managing webMethods Broker Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Chapter 4. Managing Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

4 webMethods Broker Administrator’s Guide Version 6.1

Chapter 5. Saving and Restoring Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Part III. Client Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Chapter 6. Managing Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Chapter 7. Managing Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

webMethods Broker Administrator’s Guide Version 6.1 5

Editing Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Chapter 8. Managing Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Part IV. webMethods Broker Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Chapter 9. Monitoring and Managing Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

6 webMethods Broker Administrator’s Guide Version 6.1

Chapter 10. Territories and Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Chapter 11. Managing Broker Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

webMethods Broker Administrator’s Guide Version 6.1 7

Client Access to Broker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

8 webMethods Broker Administrator’s Guide Version 6.1

Part V. Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

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

Appendix B. Tips and Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

webMethods Broker Administrator’s Guide Version 6.1 9

Adding Multiple Instances of a Broker Server to Broker Administrator . . . . . . . . . . . . . . . . 212

10 webMethods Broker Administrator’s Guide Version 6.1

About This Guide

Basic concepts of webMethods Broker architecture

webMethods Broker Administrator’s Guide Version 6.1 11

12 webMethods Broker Administrator’s Guide Version 6.1

Overview of webMethods Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Using the webMethods Broker Management Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

webMethods Broker Administrator’s Guide Version 6.1 13

webMethods Broker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

webMethods Broker Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Setting Up a webMethods Broker Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

webMethods Broker Administrator’s Guide Version 6.1 15

webMethods Broker Server

Broker Server Host

16 webMethods Broker Administrator’s Guide Version 6.1

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

Queue of documents not yet acknowledged

webMethods Broker Administrator’s Guide Version 6.1 17

Client queue storage type

Subscribe and publish access to document types

Log Publish and Log Acknowledge

Access control list

webMethods Broker Management

18 webMethods Broker Administrator’s Guide Version 6.1

Command Line Utilities

Command Line Utilities Description

webMethods Broker Administrator’s Guide Version 6.1 19

Setting Up a webMethods Broker Server

To set up a webMethods Broker Server

1 Install the webMethods Broker software.

20 webMethods Broker Administrator’s Guide Version 6.1