DECmessageQ___________________________________ Installation and Configuration Guide for UNIX Order Number: AA-PYRUB-TK December 1995 This guide contains instructions for installing, configuring, and managing DECmessageQ message queuing software on UNIX systems. Revision/Update Information: This is a revised manual. Software Version: DECmessageQ for UNIX, Version 3.1 or higher. Digital Equipment Corporation Maynard, Massachusetts __________________________________________________________ December 1995 Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Digital or an authorized sublicensor. Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description. © Digital Equipment Corporation 1991, 1995. All rights reserved. The postpaid Reader's Comments forms at the end of this document request your critical evaluation to help prepare future documentation. The following are trademarks of Digital Equipment Corporation: AXP, CDD, DEC, DECmessageQ, DECnet, DECstation, Digital, OpenVMS, PATHWORKS, RX, TK, ULTRIX, VAX, VAX C, VAXELN, VAXstation, VMScluster, and the DIGITAL logo. 88open is a trademark of the 88open Consortium, Ltd. AIX, IBM, and OS/2 are registered trademarks of International Business Machines Corporation. AppleShare, AppleTalk, Macintosh, and MacTraps are registered trademarks of Apple Computer, Inc. AT&T and NCR are registered trademarks of AT&T Global Information Solutions Company. Encina is a registered trademark of Transarc Corporation. Excel and MS-DOS are registered trademarks, and Microsoft Windows and Windows NT are trademarks of Microsoft Corporation. Hewlett-Packard and HP are registered trademarks and 9000/300, 9000/400, 9000/700, 9000/800, and HP-UX are trademarks of Hewlett-Packard Company. Intel is a trademark of Intel Corporation. Motif is a registered trademark of Open Software Foundation, Inc. Motorola is a registered trademark of Motorola, Inc. NFS, Solaris, Sun, and SunOS are registered trademarks of Sun Microsystems, Inc. PostScript is a registered trademark of Adobe Systems, Inc. SPARC is a trademark of Sparc International, Inc. THINK C is a trademark of Symantec Corporation. UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company, Ltd. Xerox is a registered trademark of Xerox Corporation. All other trademarks and registered trademarks are the property of their respective holders. This document was prepared using VAX DOCUMENT Version 2.1. ________________________________________________________________ Contents Preface.................................................. ix 1 Preparing to Install DECmessageQ Checking the Media Software Distribution Kit....... 1-1 Complying with the Installation Requirements....... 1-2 Backing up your System Disk........................ 1-2 Reviewing the Installation Options................. 1-3 Registering a Digital License PAK.................. 1-3 Registering a License Before Installing DECmessageQ Software........................................... 1-4 Registering a License After Installing DECmessageQ Software........................................... 1-5 2 Installing DECmessageQ Installing on Systems Already Running DECmessageQ Software........................................... 2-1 Installing DECmessageQ on Digital UNIX Systems..... 2-2 Installing DECmessageQ on Digital ULTRIX Systems... 2-7 Installing DECmessageQ on Other UNIX Systems....... 2-11 Error Recovery During Installation................. 2-16 Postinstallation Tasks............................. 2-16 Running the Installation Verification Procedure (IVP).............................................. 2-17 Displaying Installed Subsets....................... 2-19 Deleting Subset Options............................ 2-20 Deleting Files Extracted from the Media............ 2-20 Converting the Group Initialization File........... 2-21 Configuring the Network............................ 2-24 iii 3 Configuring UNIX System Resources for DECmessageQ Editing the Kernel Configuration File.............. 3-2 Calculating Process Resources...................... 3-3 Calculating Shared Memory Segment Resources........ 3-5 Number of Shared Segments.......................... 3-5 Size of Shared Segments............................ 3-6 Location of Shared Segments........................ 3-7 Calculating Semaphore Resources.................... 3-8 Calculating Message Resources...................... 3-10 Rebuilding the Kernel and Rebooting the System..... 3-11 Verifying System Resources......................... 3-12 4 Configuring DECmessageQ Configuring a Message Queuing Bus.................. 4-3 Configuring Message Queuing Groups................. 4-5 Creating a Standard Group Configuration Using the DMQSETUP Utility................................... 4-5 Creating a Custom Group Configuration.............. 4-8 Identifying the Group Initialization File Version............................................ 4-10 Defining the Group Profile......................... 4-11 Configuring Message Recovery....................... 4-12 Replaying Journal Messages Using the Journal Replay Utility............................................ 4-14 Running the Journal Replay Utility................. 4-14 Entering Filter Expressions........................ 4-16 Printing Journal Files Using the Journal Dump Utility............................................ 4-17 Configuring the Client Library Server.............. 4-18 Configuring Group Connections...................... 4-21 Defining Cross-Group Communications Links.......... 4-22 Defining the Message Routing Database.............. 4-24 Route Discovery.................................... 4-27 Visit Counts....................................... 4-27 Client/Server Message Routing...................... 4-28 Defining Permanent Queues.......................... 4-29 Defining Name-to-Queue Translations................ 4-34 iv 5 Managing DECmessageQ Starting and Stopping DECmessageQ Software......... 5-1 Setting Bus and Group IDs.......................... 5-2 Running the Client Library Server.................. 5-2 Starting CLS....................................... 5-3 Stopping CLS....................................... 5-4 Logging and Tracing CLS Events..................... 5-5 Monitoring Your DECmessageQ System................. 5-6 Invoking the Character-Cell UI Monitor Utility..... 5-6 Invoking the Motif UI Monitor Utility.............. 5-7 Enabling Statistics................................ 5-8 Enabling Quotas.................................... 5-9 Viewing Link and Queue Activity.................... 5-9 Viewing Link Traffic Counts........................ 5-9 Viewing Link Traffic Rates......................... 5-10 Viewing Link Traffic Detail........................ 5-12 Viewing Link Detail................................ 5-13 Viewing Queue Traffic Counts....................... 5-15 Viewing Queue Traffic Rates........................ 5-15 Viewing Queue Traffic Detail....................... 5-17 Viewing Queue Detail............................... 5-17 6 Troubleshooting Error Logging...................................... 6-1 Solving Startup Problems........................... 6-2 Solving Queue Attachment Problems.................. 6-2 A Files Installed on Your System B Sample DECmessageQ Installation on UNIX Systems Sample Installation on a Digital Alpha System ..... B-1 Sample Installation on a UNIX System .............. B-5 Sample Installation on a Digital RISC System....... B-7 v Index Examples 2-1 Listing of Installation Subset Status.... 2-20 2-2 QCT Section Prior to Conversion.......... 2-22 2-3 QCT Section After Conversion............. 2-23 4-1 Bus Initialization File.................. 4-3 4-2 Correctly Defined %XGROUP and %ROUTE Sections................................. 4-26 4-3 Incorrectly Defined %XGROUP and %ROUTE Sections................................. 4-26 B-1 Sample Installation on a Digital Alpha System................................... B-1 B-2 Sample Installation on a UNIX System..... B-5 B-3 Sample Installation on a Digital RISC System................................... B-7 Tables 2-1 Installation Subsets for Digital UNIX.... 2-2 2-2 Installation Subsets for Digital ULTRIX................................... 2-7 2-3 Installation Subsets for Other UNIX Systems.................................. 2-12 3-1 DECmessageQ for UNIX Systems Resources... 3-2 3-2 Changing System Parameters............... 3-2 3-3 Rebuilding the Kernel.................... 3-12 4-1 DECmessageQ for UNIX Configuration Options.................................. 4-1 vi 4-2 Bus Initialization File Parameters....... 4-4 4-3 Sections of the Group Initialization File..................................... 4-10 4-4 Defining the Group Profile............... 4-11 4-5 Configuring Message Recovery Services.... 4-13 4-6 Command Qualifiers for dmqjplay.......... 4-15 4-7 Command Qualifiers for dmqjdump.......... 4-18 4-8 Defining the CLS......................... 4-19 4-9 Defining Cross-Group Communications Links.................................... 4-23 4-10 Defining Routing Entries................. 4-25 4-11 Defining Permanent Queues................ 4-30 4-12 Defining Name-to-Queue Translations...... 4-35 5-1 Link Traffic Counts Dialog............... 5-10 5-2 Link Traffic Rates Dialog................ 5-11 5-3 Link Traffic Detail Dialog............... 5-12 5-4 Link Detail Dialog....................... 5-13 5-5 Queue Traffic Counts Dialog.............. 5-15 5-6 Queue Traffic Rates Dialog............... 5-16 5-7 Queue Traffic Detail Dialog.............. 5-17 5-8 Queue Detail Dialog...................... 5-18 A-1 DECmessageQ Files Installed on UNIX Systems.................................. A-1 vii ________________________________________________________________ Preface Contents of Your DECmessageQ Kit In addition to your DECmessageQ license certificate, your DECmessageQ media and documentation kit contains: __________________________________________________________ Item__________Description_________________________________ Cover letter Late-breaking news about this release and instructions for printing product release notes. Media The distribution media appropriate for your system. SPD Software Product Description describing the supported environments. Documentation Introduction to Message Queuing Installation and Configuration Guide Programmer's Guide ______________Online_help_________________________________ How to Use the Documentation The DECmessageQ documentation kit contains: o Introduction to Message Queuing-an overview of DECmessageQ features. Read this book first to learn about DECmessageQ software before installing and using it. o Installation and Configuration Guide-step-by-step instructions to install DECmessageQ software and configure your DECmessageQ environment. This guide is specific to the operating system environment in which you use DECmessageQ. ix o Programmer's Guide-a detailed description about using the DECmessageQ application programming interface to build and integrate distributed applications. Based on your role in the development and deployment of distributed applications using DECmessageQ, the following chart shows the recommended reading to learn and understand DECmessageQ quickly: __________________________________________________________ Introduction Installation to and Message Configuration Audience__Queuing_______Guide_________Programmer's_Guide__ Technical X Managers System X X Managers Application X X X Developers________________________________________________ How to Get Technical Support DECmessageQ software is covered by a one-year software warranty. If you experience a problem with DECmessageQ, you can call your local Digital customer support center for assistance. In the U.S., call 1-800-354-9000 24 hours a day, 7 days a week. Please be sure to have your license information ready when you call. In addition to the one year warranty, Digital offers a variety of software support options for DECmessageQ. To obtain more information about purchasing a support contract, contact your local Digital product distributor. We Want to Hear from You If you have questions or comments about DECmessageQ software or documentation, you can send them to us using our Internet electronic mail address: decmessageq@digital.com. You can also write to us at: DECmessageQ Engineering Digital Equipment Corporation 500 Enterprise Drive Rocky Hill, CT 06067 x If you have questions about purchasing additional Digital products or services, please call 1-800-DIGITAL. Information about Digital products and services is also available by sending E-mail to: moreinfo@digital.com Or, you can visit our World Wide Web home page at: http://www.digital.com/info/info.home.html Conventions Used in This Guide boldface Boldface type is used to distinguish routine type call arguments and command parameters when they are discussed in text. New terms, also shown in boldface type, are defined in the glossary in Introduction to Message Queuing. system This typeface indicates system output or the output exact name of a command, option, partition, pathname, directory, or file. italic Italic type emphasizes important information, type indicates variables, and indicates complete titles of books. UPPERCASE Words in uppercase indicate a command, the name of a file, the name of a file protection code, or an abbreviation for a system privilege. lowercase In format descriptions, words in lowercase indicate parameters or arguments to be specified by the user. n A lowercase italic n indicates the generic use of a number. For example, 19nn indicates a four-digit number in which the last two digits are unknown. [ ] In format descriptions, brackets indicate optional elements. . The vertical ellipsis indicates the omission . of information from an example or command . format. $ Indicates the default DCL prompt. # Indicates the default superuser prompt. Return Press the key labeled Return on the keyboard. Enter Type the information that follows and press the Return key. xii 1 ________________________________________________________________ Preparing to Install DECmessageQ This chapter describes the preparations you must make before installing DECmessageQ software on supported UNIX systems. To ensure that the installation runs smoothly, complete the following installation requirements: 1. Check the contents of the distribution kit 2. Comply with the hardware, software, and disk space requirements 3. Back up your system disk 4. Choose the installation subsets you want to install 5. Register your Digital UNIX or ULTRIX License Product Authorization Key (PAK) Checking the Media Software Distribution Kit Use the bill of materials (BOM) to check the contents of your software distribution kit. The kit contains the following: 1. Read Before Installing Letter) Your distribution kit includes a letter, Read Before Installing DECmessageQ for UNIX. This letter tells you how to access the release notes, which provide late- breaking information you should read before installing, configuring, or using DECmessageQ. 2. Media Your kit contains one of the following: o A CD-ROM for industry-standard CD-ROM readers, labeled DECmessageQ V3.1 with the specific UNIX operating system name. DECmessageQ Installation and Configuration Guide for UNIX 1-1 Preparing to Install DECmessageQ o A QIC tape cartridge for industry-standard 1/4-inch cartridge (QIC) tape drives, labeled DECmessageQ V3.1 with the specific UNIX operating system name. o A TK50 tape cartridge for TK50-compatible cartridge drives, labeled DECmessageQ V3.1 for Digital ULTRIX systems. o A 4mm DAT tape for industry-standard DAT tape readers, labeled DECmessageQ V3.1 with the specific UNIX operating system name. 3. Software Product Description The Software Product Description describes the product features and supported environments. 4. Documentation In addition to this manual, the DECmessageQ for UNIX documentation set contains: o DECmessageQ Introduction to Message Queuing o DECmessageQ Programmer's Guide o DECmessageQ Windows Client Guide Complying with the Installation Requirements Before you install DECmessageQ software you must be able to log in as the superuser on the system where you are installing DECmessageQ. Also, your system must meet the hardware, software, and disk space requirements listed in the Read Before Installing DECmessageQ for UNIX letter. Backing up your System Disk Digital recommends that you back up your system disk before installing any software. For details on performing a system disk backup, see your Digital UNIX, Digital ULTRIX, or other UNIX system documentation. 1-2 DECmessageQ Installation and Configuration Guide for UNIX Preparing to Install DECmessageQ Reviewing the Installation Options The DECmessageQ for UNIX installation dialogues display a list of options allowing you to choose which subsets to install, as follows: Development Installed on licensed systems used for Environment developing DECmessageQ applications. Run-Time Installed on all licensed systems running Environment DECmessageQ applications, including develop- ment systems. Example Programming examples that illustrate how Programs applications can use interprocess message queuing to exchange information. For more information about the programming examples, see the DECmessageQ Programmer's Guide. Client Installed on licensed systems that will Library provide Windows applications with DECmessageQ Server message queuing capabilities. Reference Reference pages provided as online Help. Pages Reference pages are not provided for HP-UX platforms. Release Important information about DECmessageQ Notes software that should be read before performing the installation. For information on how to print the Release Notes, see the letter Read Before Installing DECmessageQ for UNIX. Registering a Digital License PAK DECmessageQ software for Digital UNIX and ULTRIX systems supports the License Management Facility (LMF). For all other UNIX systems, the distribution media contains only the software licensed for use on the selected system. The LMF activates licensed use of software installed on the system. A License Product Authorization Key (License PAK) must be registered in the License Database (LDB) in order to use DECmessageQ on a newly licensed node. The License PAK is shipped with the kit if you ordered the license and media together; otherwise, it is shipped separately to a location based on your license order. The License PAKs are named: DECmessageQ Installation and Configuration Guide for UNIX 1-3 Preparing to Install DECmessageQ DMQ-DEV Development license DMQ-RTO Run-Time Only license If you are installing DECmessageQ as an update on a node already licensed for this software, you have already completed the License PAK registration requirements. If you are installing prerequisite or optional software with DECmessageQ, review the PAK status and install the PAKs for any prerequisite or optional software before you install DECmessageQ. ________________________Note ________________________ If you do not register the Digital UNIX or ULTRIX license PAK, DECmessageQ will not start. _____________________________________________________ To register a license under a Digital UNIX or ULTRIX system, first log in as the superuser. You can perform the PAK registration in the LDB either before or after installing DECmessageQ software. Registering a License Before Installing DECmessageQ Software At the superuser prompt, edit an empty PAK template in /usr/var/adm/lmf/DMQ-RTO or /usr/var/adm/lmf/DMQ-DEV with the lmf register command commands to add your unique License PAK information. o For run-time systems, add the following command: # lmf register -