TIBCO Enterprise Message Service Appliance Installation ...

Two-Seco

TIBCO Enterprise Message Service™Appliance

Installation and ReferenceSoftware Release 2.1May 2014

nd Advantage®

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDEDOR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITEDADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLEDSOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FORANY OTHER PURPOSE.USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF ALICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSEAGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USERLICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THESOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARELICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATEDIN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMSAND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND ANAGREEMENT TO BE BOUND BY THE SAME.This document contains confidential information that is subject to U.S. and international copyright laws andtreaties. No part of this document may be reproduced in any form without the written authorization of TIBCOSoftware Inc.TIBCO, Two-Second Advantage, TIB, Information Bus, and TIBCO Enterprise Message Service are eitherregistered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.All other product and company names and marks mentioned in this document are the property of theirrespective owners and are mentioned for identification purposes only.The following information is for FCC compliance: This equipment has been tested and found to comply with thelimits for a Class A digital device, pursuant to Part 15 of the FCC rules. These limits are designed to providereasonable protection against harmful interference when the equipment is operated in a commercialenvironment. This equipment generates, uses, and can radiate radio-frequency energy and, if not installed andused in accordance with the instruction manual, may cause harmful interference to radio communications.Operation of this equipment in a residential area is likely to cause harmful interference, in which case users willbe required to correct the interference at their own expense.Modifying the equipment without Pluribus Networks' written authorization may result in the equipment nolonger complying with FCC requirements for Class A digital devices. In that event, your right to use theequipment may be limited by FCC regulations, and you may be required to correct any interference to radio ortelevision communications at your own expense.You can determine whether your equipment is causing interference by turning it off. If the interference stops, itwas probably caused by the Pluribus Networks equipment or one of its peripheral devices. If the equipmentcauses interference to radio or television reception, try to correct the interference by using one or more of thefollowing measures:- Turn the television or radio antenna until the interference stops.- Move the equipment to one side or the other of the television or radio.- Move the equipment farther away from the television or radio.- Plug the equipment into an outlet that is on a different circuit from the television or radio. (That is, make certainthe equipment and the television or radio are on circuits controlled by different circuit breakers or fuses.)Modifications to this product not authorized by Pluribus Networks, Inc. could void the FCC approval andnegate your authority to operate the product.THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALLOPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAMETIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFICOPERATING SYSTEM PLATFORM.

THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS ORIMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS.CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BEINCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKEIMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED INTHIS DOCUMENT AT ANY TIME.THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY ORINDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDINGBUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.Copyright © 1997-2014 TIBCO Software Inc. ALL RIGHTS RESERVED.TIBCO Software Inc. Confidential Information

| v

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

Changes from the Previous Release of this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiTIBCO Enterprise Message Service Appliance Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiTIBCO Enterprise Message Service Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiOther TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiiiThird-Party Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiii

Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv

Connecting with TIBCO Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviHow to Join TIBCOmmunity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviHow to Access TIBCO Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviHow to Contact TIBCO Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi

Chapter 1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

Product Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2

Appliance Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4

Chapter 2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5

Installation Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6

Installing the Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7Unpack the Equipment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Install the Rack Kit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Ground the Appliance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Prevent Electrostatic Discharge Damage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Connect the Power Supply to an AC Power Source. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Verify LED Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Connect Two TIBCO Enterprise Message Service Appliances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Connect Appliance Management Port to the Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Connecting the Appliance to Your Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Connect a Console to the Appliance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Initializing the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14Access the Appliance System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Configure Appliance Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Configure Management Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Configure Host Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Configure EMS Server Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

TIBCO Enterprise Message Service Appliance Installation and Reference

vi | Contents

Configure Fault Tolerant Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Configure Disaster Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Begin Appliance Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Chapter 3 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Appliance Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Working with the File Transfer Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

EMS Server States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Appliance Monitoring. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

EMS Server Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Single Appliance Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Fault Tolerant Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Startup Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Fully Functional Condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Failover Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Restoring After a Failover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Failover Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Disaster Recovery Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Disaster Recovery Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Enabling Disaster Recovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Initial Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Verify that the EMS Server Instance on Each Appliance is Operational . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Establish Communications Between the Quad Appliances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Activate Disaster Recovery Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Rejoining the Quad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Recovering to a Backup Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Restoring the Production Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Chapter 4 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

CLI Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Using the CLI to Make Configuration Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Command Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

General Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49quit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49export-support-logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50forcestart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50halt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51


Contents | vii

info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51log-show . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51reboot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52restore-primary-active. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52setup-enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53setup-show . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53show . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53start. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54stop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54upgrade-software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54version-show. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55

Disaster Recovery Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56dr-activate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56dr-recover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56dr-restore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57key-accept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57key-join . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58key-reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58

Configuration Setup Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59config-apply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59config-pending . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59config-revert-pending . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59config-revert-unsaved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60config-review. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60config-save . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60dr-config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60ems-config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61ft-config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61hostinfo-config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61mgmt-config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61set-timezone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62syslog-config. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62


viii | Contents


| ix

Preface

TIBCO is proud to announce the latest release of the TIBCO Enterprise MessageService ™ Appliance. This release is the latest in a long history of TIBCO productsthat leverage the power of the Information Bus® to enable truly event-driven ITenvironments. To find out more about how the TIBCO Enterprise Message ServiceAppliance and other TIBCO products are powered by TIB® technology, pleasevisit us at www.tibco.com.

TIBCO Enterprise Message Service Appliance provides the latest in enterprisemessaging by offering all the benefits of TIBCO’s leading enterprise messagingsolution, TIBCO Enterprise Message Service, in a 2U appliance form factor. Withthe TIBCO Enterprise Message Service Appliance, a complete end-to-endenterprise distribution platform can be achieved without requirements on thirdparty software and hardware.

Topics

• Changes from the Previous Release of this Guide, page x

• Related Documentation, page xii

• Typographical Conventions, page xiv

• Connecting with TIBCO Resources, page xvi


www.tibco.com

x | Changes from the Previous Release of this Guide

Changes from the Previous Release of this Guide

This section itemizes the major changes from the previous release of this guide.

New Features

• TIBCO Enterprise Message Service Version This release of the appliancesupports TIBCO Enterprise Message Service software release 8.1.0. In additionto other enhancements, release 8.1.0 enables the standby server in a faulttolerant pair to remain running in standby mode, increasing performance inthe event of a failover.

• Syslog Enhancements Several syslog enhancements allow for improvedmonitoring of appliance events, including:

— Periodic scans for issues such as low disk space.

— Warnings for maintenance items, such as if one of the redundant powersupplies or fans fail.

• Update Software Configuration Most settings configured during softwareinitialization can now be changed through the command line interface (CLI).For more information, see Using the CLI to Make Configuration Changes onpage 44.

• LACP Trunk Support It is now possible to connect the ports 41 and 42 uplinkcables to separate interconnected switches as an LACP trunk, allowingadditional network-side redundancy.

• CLI Enhancements Several new features have been added to the appliancecommand line interface:

— Simplified management of the EMS servers in a fault tolerant pair usingstop, start, and forcestart.

— Easy re-balancing of servers to one on each appliance after a fault tolerantevent using restore-primary-active. As a result of this command, youno longer need to reboot the appliance to restore normal operations.

— Ability to terminate all services on an appliance in preparation forpower-down using the halt command.

• Appliance States A new section has been added describing the EMS statesthat can be seen on the appliance. See EMS Server States on page 26.


Preface | xi

Changes in Functionality

• Standalone Mode The forcestart command should now be used to start theappliance in standalone mode. This mode is used to activate an EMS serverwhen its fault tolerant peer is unavailable for synchronization. Previously, thismode was started using the start command.

• CLI Command Changes The start and stop commands no longer apply to asingle EMS server instance on the local appliance. Instead, the commandsapply to either both instances on the local appliance, or to all instances on bothappliances in a fault tolerant pair. As a result of these changes, the inputparameters for the start and stop commands have also changed.

• Appliance Setup CLI All CLI commands related to the appliance setup arenow located within a submenu of the appliance CLI. This includes thecommands dr-config and syslog-config, which were previously availablein the main CLI. For more information, see Using the CLI to MakeConfiguration Changes on page 44.

Removed Features

• Import of JSON Files The ability to import a modified JSON configuration fileto the appliance using the import command has been removed. If you requireconfiguration changes that cannot be made through Central Administration,please contact TIBCO Support for assistance.

• Fabric Names You no longer asked to supply a fabric name during appliancesetup. The appliance now automatically manages its internal fabric naming.


xii | Related Documentation

Related Documentation

This section lists documentation resources you may find useful.

TIBCO Enterprise Message Service Appliance DocumentationThe following documents form the TIBCO Enterprise Message Service Appliancedocumentation set:

• TIBCO Enterprise Message Service Appliance Installation and Reference Read thismanual for instructions on site preparation and installation, and forinstructions on using the product to administer a TIBCO Enterprise MessageService system.

• Rack Mounting Your TIBCO Chassis With Included Rail Kit Read this documentfor instructions on mounting the TIBCO Enterprise Message ServiceAppliance. A hardcopy of this document is included in the shipping box, anda PDF version can be found on the TIBCO download site.

TIBCO Enterprise Message Service DocumentationThe following documents form the TIBCO Enterprise Message Servicedocumentation set:

• TIBCO Enterprise Message Service User’s Guide Read this manual to gain anoverall understanding of the product, its features, and configuration.

• TIBCO Enterprise Message Service Central Administration Read this manual forinformation on the central administration interface.

• TIBCO Enterprise Message Service Installation Read the relevant sections of thismanual before installing this product.

• TIBCO Enterprise Message Service C & COBOL Reference The C API reference isavailable in HTML and PDF formats.

• TIBCO Enterprise Message Service Java API Reference The Java API reference canbe accessed only through the HTML documentation interface.

• TIBCO Enterprise Message Service .NET API Reference The .NET API referencecan be accessed only through the HTML documentation interface.

• TIBCO Enterprise Message Service Release Notes Read the release notes for a listof new and changed features. This document also contains lists of knownissues and closed issues for this release. This document is available only inPDF format.


Preface | xiii

Other TIBCO Product DocumentationYou may find it useful to read the documentation for the following TIBCOproducts:

• TIBCO EMS® Client for z/OS (CICS)

• TIBCO EMS® Client for z/OS (MVS)

• TIBCO EMS® Client for IBM i

Third-Party Documentation• Java™ Message Service specification, available through

http://www.oracle.com/technetwork/java/jms/index.html.

• Java™ Message Service by Richard Monson-Haefel and David A. Chappell,O’Reilly and Associates, Sebastopol, California, 2001.


http://www.oracle.com/technetwork/java/jms/index.html

xiv | Typographical Conventions

Typographical Conventions

The following typographical conventions are used in this manual.

Table 1 General Typographical Conventions

Convention Use

code font Code font identifies commands, code examples, filenames, pathnames, andoutput displayed in a command window. For example:

Use MyCommand to start the foo process.

bold code

font

Bold code font is used in the following ways:

• In procedures, to indicate what a user types. For example: Type admin.

• In large code samples, to indicate the parts of the sample that are ofparticular interest.

• In command syntax, to indicate the default parameter for a command. Forexample, if no parameter is specified, MyCommand is enabled:MyCommand [enable | disable]

italic font Italic font is used in the following ways:

• To indicate a document title. For example: See TIBCO ActiveMatrixBusinessWorks Concepts.

• To introduce new terms For example: A portal page may contain severalportlets. Portlets are mini-applications that run in a portal.

• To indicate a variable in a command or code syntax that you must replace.For example: MyCommand PathName

Keycombinations

Key name separated by a plus sign indicate keys pressed simultaneously. Forexample: Ctrl+C.

Key names separated by a comma and space indicate keys pressed one after theother. For example: Esc, Ctrl+Q.

The note icon indicates information that is of special interest or importance, forexample, an additional action required only in certain circumstances.

The tip icon indicates an idea that could be useful, for example, a way to applythe information provided in the current section to achieve a specific result.


Preface | xv

The warning icon indicates the potential for a damaging situation, for example,data loss or corruption if certain steps are taken or not taken.

Table 1 General Typographical Conventions (Cont’d)

Convention Use

Table 2 Syntax Typographical Conventions

Convention Use

[ ] An optional item in a command or code syntax.

For example:

MyCommand [optional_parameter] required_parameter

| A logical OR that separates multiple items of which only one may be chosen.

For example, you can select only one of the following parameters:

MyCommand para1 | param2 | param3

{ } A logical group of items in a command. Other syntax notations may appearwithin each logical group.

For example, the following command requires two parameters, which can beeither the pair param1 and param2, or the pair param3 and param4.

MyCommand {param1 param2} | {param3 param4}

In the next example, the command requires two parameters. The first parametercan be either param1 or param2 and the second can be either param3 or param4:

MyCommand {param1 | param2} {param3 | param4}

In the next example, the command can accept either two or three parameters.The first parameter must be param1. You can optionally include param2 as thesecond parameter. And the last parameter is either param3 or param4.

MyCommand param1 [param2] {param3 | param4}


xvi | Connecting with TIBCO Resources

Connecting with TIBCO Resources

How to Join TIBCOmmunityTIBCOmmunity is an online destination for TIBCO customers, partners, andresident experts. It is a place to share and access the collective experience of theTIBCO community. TIBCOmmunity offers forums, blogs, and access to a varietyof resources. To register, go to http://www.tibcommunity.com.

How to Access TIBCO DocumentationYou can access TIBCO documentation here:

http://docs.tibco.com

How to Contact TIBCO SupportFor comments or problems with this manual or the software it addresses, contactTIBCO Support as follows:

• For an overview of TIBCO Support, and information about getting startedwith TIBCO Support, visit this site:

http://www.tibco.com/services/support

• If you already have a valid maintenance or support contract, visit this site:

https://support.tibco.com

Entry to this site requires a user name and password. If you do not have a username, you can request one.


http://www.tibco.com/services/support

https://support.tibco.com

http://docs.tibco.com

http://www.tibcommunity.com

| 1

Chapter 1 Introduction

This chapter describes the TIBCO Enterprise Message Service Appliance and itsmajor features.

Topics

• Product Overview, page 2

• Appliance Components, page 4


2 | Chapter 1 Introduction

Product Overview

The TIBCO Enterprise Message Service Appliance is a state-of-the-art hardwareplatform that offers the full functionality of a TIBCO Enterprise Message Serviceserver. The appliance offers:

• Full EMS Server Compatibility Complete EMS server functionality. Theappliance is fully compatible with current TIBCO Enterprise Message Servicedeployments, including EMS clients and remote EMS servers.

• Multiple Configuration Options Several setup configuration options areavailable:

— Single Appliance Full EMS server functionality with a single appliance.

— Fault Tolerance Fault tolerant, guaranteed messaging for event-drivenapplications. This configuration requires two appliances.

— Disaster Recovery Backup and recovery between a production and backupsite. This configuration requires four appliances.

Figure 1 TIBCO Enterprise Message Service Appliance — Fault Tolerant Configuration


Product Overview | 3

Models

Two models of the TIBCO Enterprise Message Service Appliance are available:

• TIBCO Enterprise Message Service Appliance Standard Edition Designed foruse with SOA installations that do not have severe performance requirements,the standard edition appliance includes a hard disk drive (HDD) for messagepersistence.

• TIBCO Enterprise Message Service Appliance High Performance Edition For usein high performance installations. In addition to the HDD included in thestandard model, the high performance model also includes a solid state drive(SSD) using single-level cell (SLC) flash memory. The high performancemodel also has increased memory.

When using a fault tolerant or disaster recovery (DR) configuration, all appliancesin that configuration should be of the same model.


4 | Chapter 1 Introduction

Appliance Components

It is important to understand the roles that these components of the TIBCOEnterprise Message Service Appliance play:

• EMS Server Instance The appliance comes with the TIBCO EnterpriseMessage Service server installed and ready to run. An EMS server instance isan EMS server daemon running on the appliance. The availability of EMSserver instances depends on the appliance configuration selected, whethersingle, fault tolerant, or disaster recovery.

See EMS Server Instances on page 29 for a more complete explanation.

• Hard Disk Drive The hard disk drive (HDD) is standard on all appliancemodels. An active EMS server instance writes data, including messaging andtransaction data, to the HDD.

• Solid State Drive The SLC-based solid state drive (SSD) is available only onthe High Performance model of the appliance. When available, the EMSserver instance can write messaging and transaction data to the SSD or HDD.

• Command Line Interface Once powered on, the appliance is controlled usingcommands issued on the command line interface (CLI). For more information,see Chapter 4, Commands.

Figure 2 shows the relationship between these primary appliance components ina fault tolerant configuration.

Figure 2 TIBCO Enterprise Message Service Appliance Components


| 5

Chapter 2 Installation

This chapter describes the installation of the TIBCO Enterprise Message ServiceAppliance.

Topics

• Installation Requirements, page 6

• Installing the Hardware, page 7

• Initializing the Software, page 14


6 | Chapter 2 Installation

Installation Requirements

HardwareRequirements

When installing the TIBCO Enterprise Message Service Appliance, follow theseguidelines:

• Ensure that there is adequate space around the appliance to allow forservicing the appliance and for adequate airflow.

Airflow enters the chassis through the bezel and fan modules and exhauststhrough the port connections end of the chassis. You must install the TIBCOEnterprise Message Service Appliance with its bezel and fan modules locatedin a cold aisle.

• Ensure that the air conditioning meets the heat dissipation requirements:

— Temperature: 32 to 104F (0 to 40°C)

— Humidity: 10 to 85% (non condensing)

• Ensure that the appliance is going to be positioned so that it takes air from acold aisle and exhausts air to a hot aisle. The end of the chassis with the bezeland fan modules must be positioned in a cold aisle.

• Ensure that the chassis can be adequately grounded. If the appliance is notmounted in a grounded rack, we recommend connecting both the systemground on the chassis and the power supply ground directly to anearthground.

• Ensure that the site power meets the power requirements:

— Maximum output power: 510 W

— Input voltage: 100 to 240 VAC

— Frequency: 50 to 60 Hz

— Efficiency: 90/92% (110/240 Vin) at typical power draw and 88/91%(110/240 Vin) at max power draw

— RoHS-6 compliant

If available, you can use an uninterruptable power supply (UPS) to protectagainst power failures.

• Ensure that circuits are sized according to local and national codes. For NorthAmerica, the power supply requires a 15 Amp or 20 Amp circuit.


Installing the Hardware | 7

Installing the Hardware

When lifting the switch chassis, follow these guidelines:

• Disconnect all power and external cables before lifting the switch.

• Ensure that your footing is solid and the weight of the switch is evenlydistributed between your feet.

• Lift the switch slowly, keeping your back straight. Lift with your legs, not withyour back. Bend at the knees, not at the waist.

Follow these steps to install the TIBCO Enterprise Message Service Appliance.

Task A Unpack the Equipment

Compare the shipment to the equipment list provided by your customer servicerepresentative and verify that you have received all items, including thefollowing:

• Grounding lug kit

• Rack-mount rail-kit

• ESD wrist strap

• Cables with connectors

• Any optional items ordered

Check for damage and report any discrepancies or damage to your customerservice representative.

Task B Install the Rack Kit

The TIBCO Enterprise Message Service Appliance can be installed in thefollowing types of racks using a rail-kit shipped with the appliance:

• Open EIA rack

— The minimum vertical rack space per chassis must be two rack units (RU),equal to 3.47 inches (8.8 cm).

— The horizontal distance between the chassis and any adjacent chassisshould be 6 inches (15.2 cm), and the distance between the chassis air ventsand any walls should be 2.5 inches (6.4 cm).



• Perforated EIA cabinet

— The front and rear doors must have at least a 60 percent open areaperforation pattern, with at least 15 square inches (96.8 cm2) of open areaper rack unit of door height.

— The roof should be perforated with at least a 20 percent open area.

— The cabinet floor should be open or perforated to enhance cooling.

The rail-kit enables you to install the appliance into racks of varying depths. Youcan use the rail-kit parts to position the appliance with easy access to either theport connections end of the chassis or the end of the chassis with the fan modules.For instructions on how to use the rail-kit, see the Rack Mounting Your TIBCOChassis With Included Rail Kit document included with the appliance.

Task C Ground the Appliance

Grounding is one of the most important parts of equipment installation. Propergrounding practices ensure that the buildings and the installed equipment withinthem have low-impedance connections and low-voltage differentials betweenchassis. When you properly ground systems during installation, you reduce orprevent shock hazards, equipment damage due to transients, and datacorruption. Table 3 lists some general grounding practice guidelines.

Table 3 Proper Grounding Guidelines

Environment ElectromagneticNoise Severity Level Grounding Recommendations

Commercial building issubjected to direct lightningstrikes.

For example, some places inthe United States, such asFlorida, are subject to morelightning strikes than otherareas.

High All lightning protection devices must beinstalled in strict accordance withmanufacturer recommendations.

Conductors carrying lightning currentshould be spaced away from power anddata lines in accordance with applicablerecommendations and codes.

Best grounding recommendations mustbe closely followed.

Commercial building is locatedin an area where lightningstorms frequently occur but isnot subject to direct lightningstrikes.

High Best grounding recommendations mustbe closely followed.



To ground the TIBCO Enterprise Message Service Appliance and prevent damagefrom electrostatic discharge:

1. Use a wire-stripping tool to remove approximately 0.75 inches (2 cm) of theinsulation from the end of the grounding cable.

2. Insert the stripped end of the grounding cable into the open end of thegrounding lug.

3. Use the crimping tool to secure the grounding cable in the grounding lug.

Commercial building containsa mix of informationtechnology equipment andindustrial equipment, such aswelding.

Medium to High Best grounding recommendations mustbe closely followed.

Existing commercial buildingis not subject to naturalenvironmental noise ormanmade industrial noise.This building contains astandard office environment.This installation has a historyof malfunctions due toelectromagnetic noise.

Medium Determine source and cause of noise ifpossible, and mitigate as closely aspossible at the noise source or reducecoupling from the noise source to theaffected equipment.

Best grounding recommendations mustbe closely followed.

New commercial building isnot subject to naturalenvironmental noise ormanmade industrial noise.This building contains astandard office environment.

Low Electromagnetic noise problems are notanticipated, but installing a groundingsystem in a new building is often theleast expensive route and the best wayto plan for the future.

Best grounding recommendationsshould be followed as much as possible.

Existing commercial buildingis not subject to naturalenvironmental noise ormanmade industrial noise.This building contains astandard office environment.

Low Electromagnetic noise problems are notanticipated, but installing a groundingsystem is always recommended.

Best grounding recommendationsshould be followed as much as possible.

Table 3 Proper Grounding Guidelines

Environment ElectromagneticNoise Severity Level Grounding Recommendations



4. Remove the adhesive label from the grounding pad on the chassis.

5. Place the grounding lug against the grounding pad so that there is solidmetal-to-metal contact, and insert the two M4 screws with washers throughthe holes in the grounding lug and into the grounding pad.

6. Ensure that the lug and cable do not interfere with other equipment.

7. Prepare the other end of the grounding cable and connect it to an appropriategrounding point in your site to ensure adequate earth ground.

Task D Prevent Electrostatic Discharge Damage

Electrostatic discharge (ESD) damage, which can occur when modules and otherfield-replaceable units (FRUs) are improperly handled, results in intermittent orcomplete failures. Modules consist of printed circuit boards that are fixed in metalcarriers. Electromagnetic interference (EMI) shielding and connectors are integralcomponents of the carrier. Although the metal carrier helps to protect the boardfrom ESD, always use an ESD grounding strap when handling modules.

If you choose to use the disposable ESD wrist strap supplied with most FRUs oran ESD wrist strap equipped with an alligator clip, you must attach the systemground lug to the chassis in order to provide a proper grounding point for theESD wrist strap.

1. Attach the ESD wrist strap to bare skin as follows:

a. If you are using the ESD wrist strap supplied with the FRUs, open thewrist strap package and unwrap the ESD wrist strap. Place the blackconductive loop over your wrist and tighten the strap so that it makesgood contact with your bare skin.

b. If you are using an ESD wrist strap equipped with an alligator clip, openthe package and remove the ESD wrist strap. Locate the end of the wriststrap that attaches to your body and secure it to your bare skin.

2. Grasp the spring or alligator clip on the ESD wrist strap and briefly touch theclip to a bare metal spot (unpainted surface) on a grounded rack. Werecommend that you touch the clip to an unpainted rack rail so that anybuilt-up static charge is safely dissipated to the entire rack.

3. Attach either the spring clip or the alligator clip to an earth ground (groundedrack or the screw holding a grounding lug to the chassis):

a. If you are using the ESD wrist strap that is supplied with the FRUs,squeeze the spring clip jaws open, position the spring clip to one side of



the system ground lug screw head, and slide the spring clip over the lugscrew head so that the spring clip jaws close behind the lug screw head.

b. If you are using an ESD wrist strap that is equipped with an alligator clip,attach the alligator clip directly over the head of the system ground lugscrew or to the system ground lug barrel.

To attach the ESD wrist strap to the system ground lug screw for the TIBCOEnterprise Message Service Appliance, clip the grounding wire to the screw thatattaches the grounding lug to the switch chassis.

Task E Connect the Power Supply to an AC Power Source

1. Verify that the AC power source is turned off at the circuit breaker.

2. Plug the power cable into the power receptacle on the power supply.

3. Attach the other end of the power cable to the AC power source.

4. Turn on the power at the circuit breaker.

5. Verify that the power supply is functioning by making sure that the OK LEDturns green and the FAULT LED is off.

Task F Verify LED Operation

After the appliance boots, verify that the LED operation is as follows:

• PWR — Power LED is green.

• STAT — Status LED is green.

• ATTN — Attention LED is off.

• FAIL — Failure LED is off.

If after the switch boots the system status (STAT) LED is amber, one or morechassis environmental or diagnostic monitors is reporting a problem.

Task G Connect Two TIBCO Enterprise Message Service Appliances

To connect two TIBCO Enterprise Message Service Appliance for use in a faulttolerant configuration, connect ports numbered 30, 31, and 32 on the first box withthe matching ports on the second box.

• For best performance, use fiber optic cables to connect the two appliances.

• Three connections are required.



Task H Connect Appliance Management Port to the Network

To connect an external switch to the appliance:

1. Connect the appropriate cable to the Ethernet connector on you networkswitch.

2. Connect the other end of the cable to the MGMT1 port on the appliance.

Task I Connecting the Appliance to Your Network

The TIBCO Enterprise Message Service Appliance is configured to support dualuplink ports to the network.

To connect the appliance to your network:

1. Insert transceivers into ports 41 and/or 42.

Either 1 or 10 gigabit transceivers are supported.

2. Connect the transceivers to your network using 10 gigabit cables.

Task J Connect a Console to the Appliance

Initial software setup must be completed on a console connected to the appliance.After the software is initialized, you can connect to the appliance using SSH. Youcan either connect a monitor and keyboard directly to the appliance, or connect acomputer using an RJ-45 serial cable:

• Connect a Monitor and Keyboard to the Appliance:

1. Connect a USB keyboard to the appliance. You may use any USB port onthe appliance, front or back.

2. Connect a monitor using the 15-pin VGA port on the back of the back ofthe appliance.

3. Ensure that the monitor is plugged in and powered on. If a prompt doesnot automatically appear on the monitor screen, hit Enter on the keyboard.

• Connect a Computer Using an RJ-45 to DB-9 Serial Cable:

Ports 41 and 42 are configured in an active-mode Link Aggregation ControlProtocol (LACP). These ports must uplink to network ports that are alsoconfigured for LACP. Ports 41 and 42 can be uplinked to two separate networkswitches as long as these switches support LACP ports across multiple switches.Please consult your switch manufactures documentation to enable this.



1. Configure the terminal emulator program to match the following defaultport characteristics: 9600 baud, 8 data bits, 1 stop bit, no parity.

2. Connect the RJ-45 connector of the console cable to the CONSOLE portand the DB-9 connector to the computer serial port.

When the monitor is connected, proceed to Initializing the Software below.



Initializing the Software

After the TIBCO Enterprise Message Service Appliance has been installed, youmust initialize the software before the appliance can be used. This processconfigures the default appliance users, creates the EMS server instance(s), andsets the IP addresses used to adminster the appliance and connect to the EMSservers using Central Administration.

Task A Access the Appliance System

1. Power on the TIBCO Enterprise Message Service Appliance system.

2. Access the appliance using the console, as described in Task J, Connect aConsole to the Appliance above.

3. At the prompts, enter the information specific to your system. The sectionsbelow describe the information requested in greater detail.

The appliance runs a health check before starting the software initialization. Ifit detects any problems, such as an error in the operating system or hardware,it reports an error. Do not proceed with software initialization without firstaddressing and resolving any errors. Contact TIBCO Support if you requireassitance.

Note that all IP addresses must be specified using IPv4 addresses. The appliancedoes not support IPv6.


Initializing the Software | 15

Task B Configure Appliance Users

The users you configure here have access to the TIBCO Enterprise MessageService Appliance, as described in Appliance Users on page 22.

Task C Configure Management Information

Set passwords? [y/n] (yes):

Enter y to change the default passwords for the applianceusers.

Enter n to accept the default passwords. The defaultpassword for the tibadm user is test123. The defaultpassword for the tibfile user is test123.

Note that passwords, once set, cannot be changed withoutthe assistance of TIBCO Support.

Password for tibadm:

Select a password for the tibadm user.

Re-enter Password:

Enter the tibadm user password again.

Record your tibadm password in a secure location. TIBCO cannot access theappliance or otherwise recover a system without the tibadm password.

Password for tibfile:

Select a password for the tibfile user.

Re-enter Password:

Enter the tibfile user password again.

Hostname ():

Enter a name to identify this TIBCO Enterprise MessageService Appliance.



Task D Configure Host Information

Mgmt IP/Netmask (/):

Enter the IP address that will be used by the predefinedappliance users to access the management interface of theTIBCO Enterprise Message Service Appliance, followed bythe network mask.

For example:10.101.1.100/24

Mgmt Gateway IP ():

For example:10.101.1.1

Primary DNS IP ():

Optional. For best results, enter a DNS IP address. Forexample:10.201.1.100

Secondary DNS IP ():

Optional. For example:10.201.1.101

Domain Name ():

For example:company.com

NTP Server ():

For example:0.us.pool.ntp.org

Time zone ():

Time zone of location in which appliance will be used.

Specify the time zone by entering a time zone name from thetz database. For example, America/New_York or US/Easternare both valid settings. Lists of time zone names are availableonline:http://en.wikipedia.org/wiki/List_of_tz_database_time_zones.


http://en.wikipedia.org/wiki/List_of_tz_database_time_zones



Task E Configure EMS Server Information

EMS Server IP/Netmask ():

This is the EMS Server IP address that will be used by clientsoftware when connecting to the EMS server. For example:192.168.3.51/24

EMS Server Gateway IP:

Optional. If an IP address is specified here, the EMS Gatewayaddress becomes the primary routed network to theappliance once the appliance is operational. If the EMSGateway is not supplied (or is not reachable), the requiredMgmt Gateway is used instead. Supplying both Gatewaysaccommodates instances where the management port isconnected to a different network from the EMS server port,and allows EMS clients to connect over a routed network.

When the EMS Server Gateway IP is supplied and isoperational, SSH access to the CLI uses the EMS server IPaddress instead of the Mgmt IP address.

Uplink Speed in gigabits (1 or 10):

Specify an uplink speed, either 1 or 10 Gb (gigabits).

EMS Instance Name ():

Enter a name for the EMS server instance. For example,server-0.

For server naming conventions, see documentation for theserver parameter in the TIBCO Enterprise Message ServiceUser’s Guide.



Task F Configure Fault Tolerant Behavior

EMS Instance IP Port ():

Enter the port number to be used by EMS clients connectingto the EMS server instance.

This port is used with the EMS Server IP address to create theserver’s listen setting. Appliances in a fault tolerant pairmust use different port numbers. For example, if EMSinstance 0 uses port 7222, EMS instance 1 might use port7223.

NOTE: When setting up a Backup Site appliance for disasterrecovery, be aware that the port number entered here willonly be used for initial testing. When the Production Site isrecovered to the backup site, this information is overwrittenand the port numbers will be the same as the originalproduction site port numbers.

Is this in a Fault-Tolerant pair (yes):

Hit enter if this appliance is connected to a second TIBCOEnterprise Message Service Appliance as part of afault-tolerant pair.

If this appliance is intended to run as a single installation,type n and hit enter and proceed to Task H.

Primary Instance (0 or 1) on local EMS Server ():

Enter 0 if the primary EMS server instance on the applianceshould be identified as instance 0. Enter 1 if the primary EMSserver instance should be instance 1.

EMS Server Instance Name of the other host of the FT pair ():

Enter the EMS Instance Name used to identify the EMSserver instance on the second appliance in the fault tolerantpair. This name is set in Task E.

For example, inst1.

EMS Server IP of the other host of the FT pair ():

Enter the EMS server IP address for the other appliance in thefault tolerant pair. This address is used to configure thesecondary listen URL for the secondary EMS server instance.



Task G Configure Disaster Recovery

EMS Server Port of the other host of the FT pair ():

Enter the port number that should be used by the EMS serveron this appliance when connecting to its fault tolerant peeron the second appliance.

Is this unit in a disaster recovery configuration? (yes/no):

If this appliance will be part of a disaster recoveryinstallation, enter yes.

For more information on disaster recovery and itsrequirements, see Disaster Recovery Configuration onpage 36.

If the appliance is not part of a disaster recoveryinstallation, type no and hit enter and proceed to Task H.

Is this a backup unit for disaster recovery? (yes/no):

Enter yes if this appliance is located at the backup site.

Enter no if the appliance is part of the production site.

EMS Server IP of the Backup-A appliance ():

This prompt appears only if your previous responseshave indicated that the appliance is:

• is instance 0 in its fault-tolerant pair

• is part of a disaster recovery installation

• is part of the production site

Specify the IP address of the Backup-A appliance.

EMS Server IP of the Backup-B appliance():

This prompt appears only if your previous responseshave indicated that the appliance is the Production-Aappliance, or:



• is part of the production site

Enter the IP address for the Backup-B appliance.



Task H Begin Appliance Operations

Once you have responded to the final prompt, your configuration is saved. ClickEnter to automatically log in as the tibadm user and access the CLI prompt:

EMS CLI >

The EMS server instances start automatically and can be accessed through CentralAdministration, using the EMS Server IP address and the EMS instance IP portsspecified during software initialization.

When the EMS server is active, you can see the EMS server URL by entering theinfo command from the CLI.

Data backup interval in minutes (must be >= 1.0) ():

This prompt appears only if your previous responseshave indicated that the appliance:



• is part of the production site (a no at the previousprompt)

Specify the interval at which updated system informationis sent from the production site to the backup site. Forexample, enter 7.5 to have an update sent every sevenand a half minutes.

EMS Server IP of the Production-A appliance ():

This prompt appears only if your previous responseshave indicated that the appliance is:


• is part of the backup site

Enter the IP address for the Production-A appliance.


| 21

Chapter 3 Configuration

This chapter explains how to configure the TIBCO Enterprise Message ServiceAppliance.

Topics

• Appliance Users, page 22

• EMS Server States, page 26

• Appliance Monitoring, page 28

• EMS Server Instances, page 29

• Single Appliance Configuration, page 30

• Fault Tolerant Configuration, page 31

• Disaster Recovery Configuration, page 36


22 | Chapter 3 Configuration

Appliance Users

The TIBCO Enterprise Message Service Appliance is accessed through a networkconnection, or through a console connected to the appliance. The appliance canonly be accessed using predefined SSH or SFTP accounts using the IP addressspecified during software initialization. See CLI Overview on page 44 forinformation accessing the appliance using SSH and SFTP.

Three preconfigured users have access to the TIBCO Enterprise Message ServiceAppliance:

• tibadm — The tibadm account is used to issue commands to manage theappliance. Use SSH to login to the appliance as tibadm.

The EMS appliance automatically launches the CLI when the login process iscomplete. Using commands, this user is able to perform such administrativeactivities as starting an EMS server instance, copying log and core files to thefile transfer directory with the export command, and updating SSLcertificates and EMS server configuration files by way of the importcommand. For more information on these commands, see Chapter 4,Commands.

The password for the tibadm user is determined when the appliance is firstconfigured. See Initializing the Software on page 14 for more information. Ifyou have forgotten the password or need to change it, contact TIBCO Support.

• tibfile — The tibfile account is used to transfer files to and from theappliance. Use SFTP to login to the appliance as tibfile, as described belowin Working with the File Transfer Directory. As tibfile you are able to:

— Retrieve files placed in the directory by the tibadm user.

— Add files to the directory for deployment by the tibadm user.

Only SFTP transfers are available. SCP transfers cannot be used.

The password for the tibfile user is determined when the appliance is firstconfigured.

• admin — The admin user is for use only when working with TIBCO support,and has complete access to the appliance by way of SSH. In order to log on asthe admin user, you must first log in using the tibadm password, and thencorrectly respond to a challenge question.


Appliance Users | 23

Working with the File Transfer DirectoryThe tibfile user can login to the appliance through SFTP at the IP addressspecified during software initialization. If the appliance was configured with anEMS Server Gateway, use that IP address to connect. Otherwise, connect throughthe management IP address.

The tibfile user automatically accesses the tib-transfer directory upon login.

The file transfer directory holds several types of files:

• Copies of deployed configuration and SSL certificate files that have beenadded by the tibadm user.

• Log and core report files that have been moved to the file transfer directory bythe tibadm user.

• Modified or new files that have been uploaded by the tibfile user.

Table 4 shows the structure of the tib-transfer directory.

Table 4 File Transfer Directory Structure

Directory Contents

/instance-X/certs Contains SSL certificate files.

This directory contains any SSL certificate files thathave been exported by the tibadm user. See theexport command for details.

To deploy new SSL certificate files, add them to thisdirectory. Uploaded files can then be deployed bythe tibadm user. For details, see the importcommand.



/instance-X/config Contains the EMS server configuration files.

The tibadm user can export copies of these files tothe config directory:

• tibemsd.json — the deployed EMS serverconfiguration file.

• tibemsd.config — EMS server command linearguments.

• emsd.pathmap — logical store location mapping.

• emsa_params.json — lists setup parametersconfigured in appliance.

• emsa_emsmon.config — syslog subscriptionsfor server messages.

See the export command for details.

/instance-X/cores Contains core reports.

The tibadm user can export any core reports to thisdirectory. See the export command for details.

/instance-X/logs Contains log files.

In addition to regular event log files, thedr_params.log log file is generated duringinitialization, and lists all disaster recoveryparameters. These logs are saved under instance 0.

The tibadm user can export any server log files tothis directory. See the export command for details.

/system/import Contains software updates.

Upload TIBCO Enterprise Message ServiceAppliance software upgrade packages to thisdirectory for installation.

After the package has been uploaded, it can beinstalled by the tibadm user. For details, see theupgrade-software command.


Directory Contents


Appliance Users | 25

/system/export Contains log files for TIBCO support that are createdwhen the CLI command export-support-logs isissued.


Directory Contents



EMS Server States

The EMS server state provides information about how the EMS server isoperating in the appliance.

Use the info command to determine the server state. Table 5 describes thepossible states.

Table 5 EMS Server States within the Appliance

State Description

Singular

On an appliance, the EMS server state described here is only applicable tosingle appliance configurations.

active The server is fully operational and ready toservice clients.

Fault Tolerant

The EMS server states described here are only applicable to EMS servers in afault tolerant configuration.

active-paused The server is in active state and is determining thecorrect action in reaction to failure of the standbyserver.

active-replicating The server is in active state and is replicatingincoming data to the standby server.

active-standalone The server is active but not synchronizing datanor replicating incoming data to the standbyserver because it cannot reach it.

active-synchronizing The server is in active state and is synchronizingdata to the standby server.

disabled The server has been stopped by the user throughthe CLI command stop.

standby-paused The server is in standby state and is determiningthe correct action in reaction to failure of theactive server.


EMS Server States | 27

standby-replicating The server is in standby state and is currentlyreplicating incoming data from the active server.

standby-synchronizing The server is in standby state and is currentlysynchronizing data from the active server.

wait-for-peer The EMS server is waiting for its peer to connect.

Most frequently, this state is seen when there is adelay between startup of the primary andsecondary servers in a fault tolerant pair.

Table 5 EMS Server States within the Appliance

State Description



Appliance Monitoring

The appliance regularly writes log messages to a local file, which can be accessedthrough the tibfile user. In addition to these default logs, you can configure theappliance to transmit messages of higher importance to a remote syslog daemon,or collector.

When syslog transmision is enabled, all messages of priority warning and higherare transmitted to the collector. This can be used to monitor the appliance forsignificant events, including:

• Server state changes

• Appliance fan failure

• Power supply failure

• Low disk space

• Disk errors

Syslog monitoring is configured with the syslog-config command.


EMS Server Instances | 29

EMS Server Instances

An EMS server instance is an EMS server daemon running on the appliance. TheTIBCO Enterprise Message Service Appliance identifies a running EMS serverinstance as either instance 0 or instance 1. The instance number is set when theappliance software is initialized. This process is described in Initializing theSoftware on page 14.

The availability of EMS server instances depends on the appliance configuration.

• Single Appliance Configuration In a single appliance deployment, only oneinstance is available. This instance is always instance 0, and runs instandalone mode.

• Fault Tolerant Configuration When two appliances are connected in a faulttolerant pair, instance 0 is primary on one appliance and instance 1 is primaryon the other.

Both appliances in a fault tolerant pair may not use the same instance numberfor their primary EMS servers. One appliance must be configured to have itsprimary EMS server be instance 0 and the other must have its primary EMSserver be instance 1.

• Disaster Recovery Configuration When four appliances are configured fordisaster recovery, each pair in the quad is set up similar to a fault tolerantconfiguration. That is, at each site there is an appliance with an EMS serverinstance 0 designated as primary, and a second appliance where the primaryEMS server instance is identified as instance 1.

These configuration options are described in greater detail in the sections below.

ConfigurationOnce the EMS server instance is started, you should configure the server usingCentral Administration.

Please note that some EMS features are not available to appliance users. In manycases, these features are hidden in Central Administration in order to protect youfrom appliance misconfigurations. The Server List in the Central Administrationweb interface denotes appliances with the icon.

Accessing Central Administration

For more information on using Central Administration, see the TIBCO EnterpriseMessage Service Central Administration guide in the TIBCO Enterprise MessageService documentation.



Single Appliance Configuration

Although most TIBCO Enterprise Message Service Appliance installations deploytwo appliances in a fault tolerant pair, it is possible to run a single appliance.

In a single appliance scenario, fault tolerance is not available. If the EMS serverinstance fails, there is no backup instance.

Figure 3 Single Appliance Deployment


Fault Tolerant Configuration | 31

Fault Tolerant Configuration

Fault tolerance is deployed using two TIBCO Enterprise Message ServiceAppliances which are started at the same time and communicate over a cabledconnection. Each appliance contains a primary EMS server instance and asecondary EMS server instance that is activated in the event of a failure of itsprimary instance. All switches and EMS clients are connected to both appliances,allowing the secondary EMS server instance to take over from the primaryinstance in the event of a failure.

Figure 4 shows the fault tolerance configuration of two TIBCO EnterpriseMessage Service Appliances.

Figure 4 Fault Tolerant Configuration

All appliances in a fault tolerant configuration should be of the same model,either standard or hi-performance. For best results, both appliances should alsouse the same EMS appliance software version.



Startup ProcessWhen a pair of fault-tolerance appliances start up, the procedure described heretakes place concurrently on each appliance.

1. When the EMS server instance starts, it waits for its peer before proceedingwith the startup sequence.

2. After contact occurs, the two EMS server instances check the state of theirstores to determine which server has the most recent copy of the store data.

3. The EMS server that has the latest store data proceeds to the active state andbegins servicing clients. The other server proceeds to the standby state.

4. The active and standby EMS servers synchronize data, such as store andconfiguration files, to ensure that both sides match. Synchronization iscomplete when both servers have the same records in their store files.

5. The active and the standby servers begin replicating data. Replication is theprocess whereby the active EMS server instance writes persistent data to bothits own and the standby server store files.

Fully Functional ConditionUnder fully functional conditions, both the active and standby EMS serverinstances write persistent data to their store files. When needed, the active EMSserver reads data from its local store file.

If only one appliance in a fault tolerant pair is available, you can force the EMSserver instance(s) on the available appliance to start in standalone mode. Startingan EMS server instance in a standalone mode requires an explicit command fromthe administrator using the forcestart command on the CLI. Neither appliancewill automatically start servicing messaging operations in the absence of theother.

When the second appliance is started, it synchronizes with the appliance that wasforced to start. You should never force both appliances to start separately becausethey cannot properly synchronize their stores afterwards.



Failover ProcessWhen a fault tolerant appliance loses contact with its peer, both the active andstandby EMS server instances enter their paused states for a short time while theappliance determines the correct action.

The response of the appliance depends on the type of failure experienced:

• System or Power Failure

If the peer appliance is down, the remaining appliance's active EMS serverinstance enters the active-standalone state and continues to service clients.The standby EMS server instance also enters the active-standalone state, andbegins servicing clients.

Note that no replication occurs while the servers are in the standalone state.

• Hardware Component Failure

If both appliances are still running but one appliance has a hardware fault, thefaulted appliance shuts down its active EMS server instance. Both EMS serverinstances on the functional appliance begin servicing clients in theactive-standalone state.

• Connection Failure

If the fiber optic cable connections between the appliances fail, preventing theEMS server instances from communicating, the appliances continue theiractive server instance in the standalone state and prevent their standby EMSserver instance from being able to activate.

• Network Interface Failure

If an appliance has a network interface failure that prevents its EMS serverinstances from servicing clients (even though the EMS server instances cancommunicate with their peers on the other appliance), the appliances react inthe same way as they would to a hardware failure.



Restoring After a FailoverTo restore the fully functional condition, simply start the appliance that is down.

The EMS server instances on the restarted appliance automatically contact theirpeers in the functional appliance. The EMS servers in the functional appliance,which have been operating in active-standalone state, enter theactive-synchronizing state while continuing to service messaging clients.

When synchronization is complete, both EMS server instances on the functionalappliance transition to the active-replicating state. Both servers on the newlystarted appliance then transition to the standby-replicating state. Use therestore-primary-active command on the CLI to rebalance the EMS serverinstances so that EMS server instance 0 is active on the primary appliance andEMS server instance 1 is active on the secondary appliance.

Failover EventsThe events that result in a failover, and the response to each event by the primaryand secondary EMS server instances are described in Table 6.

Restoring the primary EMS server to the active state causes client connections todrop and reconnect, as the active server moves from one appliance to the other.

Table 6 Fault Tolerance — Failover Events

Event Active EMS InstanceReaction

Standby EMSInstance Reaction

Failure of the active EMSserver instance, other thana write failure.

The EMS serverattempts to restart andsynchronize with theactivated standbyserver.

Activates the EMSserver instance andbegins local writes.

Failure of the active EMSserver hardware.

— Activates the EMSserver instance andbegins local writes.

Failure of the standbyEMS server hardware.

Performs local writesonly.

—

An internal system erroron the active appliance.

Stops the EMS serverinstance.




An internal system erroron the standby appliance.


Cannot be activated.

Active EMS server localwrite fails.

Stops the EMS serverinstance.


Standby EMS server localwrite fails.


The EMS serverrestarts.

Failure of the standbyEMS server, other thanwrite failure.


The EMS serverattempts to restart andsynchronize with theactive server.

Table 6 Fault Tolerance — Failover Events

Event Active EMS InstanceReaction

Standby EMSInstance Reaction



Disaster Recovery Configuration

You can configure your appliance installation for disaster recovery (DR). Adisaster recovery configuration consists of two appliances at a production sitematched with two appliances at a back-up site. Should there be a failure in theproduction site, you can recover activity at the back-up location. When theproduction site is back online, you can then restore activity at that location.

Structure

Disaster recovery requires four appliances, known as a quad. A quad is dividedinto two fault-tolerant pairs, the production pair and the backup pair. The termsproduction and backup here indicate the physical location, or site, of the appliances.

The appliances at the production site are designated Production-A andProduction-B, whereas the appliances at the backup site are designated Backup-Aand Backup-B. An appliance's designation is distinct from but related to its role.

The relationships between the quad of appliances is shown in Figure 5.

All appliances in a DR configuration should be of the same model, either standardor hi-performance. For best results, both appliances should also use the same EMSappliance software version.


Disaster Recovery Configuration | 37

Figure 5 Disaster Recovery Structure

Roles

There are two roles in disaster recovery: DR leader and DR member.

In most cases, Production-A is the DR leader, while the three remainingappliances, Production-B, Backup-A and Backup-B, are DR members.



Disaster Recovery ProcessWhen configured, disaster recovery works as follows:

1. At regular intervals, the production site takes a snapshot of filesystem datafrom its active server instances and sends this snapshot to an appliance at thebackup site.

Under normal, fully operational behavior, Production-A sends instance 0snapshots to Backup-A, and Production-B sends instance 1 snapshots toBackup-B.

2. If Production-A fails, both EMS server instances 0 and 1 are running onProduction-B. Assuming both backup site appliances are available,Production-B begins sending instance 0 snapshots to Backup-A, and continuessending instance 1 snapshots to Backup-B.

3. If both Production-A and Production-B fail, you must manually initiate theDR recovery procedure at the backup site. See Recovering to a Backup Site onpage 41 for details.

Note that disaster recovery does not imply that there is no data loss. Anyactivity that occurred after the most recent snapshot may be lost. The recoveryprocess erases all prior data from the backup site and overwrites it with thedata from the production site snapshot.

4. If at the time of a DR event only one appliance is available at the backup site,the disaster recovery process can be initiated on the available appliance. Forexample, if the backup site experienced an FT event or planned downtime onone of the appliances, the client operations can still be recovered at the backupsite.

5. When the production site is restored, it must be reactivated manually usingthe dr-restore command.

You should not start the EMS server instance on an appliance while it is actingas a backup. In case of a recovery event, the data from previous activity usingthose servers may be lost.



Enabling Disaster RecoveryYou can activate DR only after the initial setup is complete on all four appliances,connectivity exists, and all four roles have been correctly established.

Task A Initial Setup

The first step in disaster recovery setup is to configure the software. For eachappliance in the quad, you specify that it will be used for disaster recovery andwhether the appliance is part of the production or backup site. You also provideany needed IP addresses of other members of the quad.

You are prompted for this information during software initialization of a newappliance. However, you can also add DR configuration later using thedr-config command.

For information about the disaster recovery settings configured during softwareinitialization, see Initializing the Software on page 14.

Task B Verify that the EMS Server Instance on Each Appliance isOperational

Before establishing communications between the quad appliances, ensure that theEMS server instance on each appliance is fully operational. To verify the EMSserver state, use the info command on the CLI.

For the Production-A and Backup-A appliances, the state of instance 0 should beactive-replicating. The state of instance 1 should be standby-replicating.

For the Production-B and Backup-B appliances, the opposite is true: instance 0should be standby-replicating, and instance 1 should be active-replicating.

Task C Establish Communications Between the Quad Appliances

Use the key-accept and key-join commands to establish communicationsbetween the appliances in the DR cluster:

1. On the DR leader (Production-A), issue the key-accept command.

2. On each of the DR members, issue key-join.

The key is a key-pair automatically generated by the DR leader during initialsetup. When you issue key-accept, the DR leader permits DR members toretrieve and install the DR key when key-join is issued. All DR members use thesame DR key.

Appliances in the DR cluster exchange SSH Secure Shell keys. Consequently, SSHport 22 must be open between members of the quad.



Task D Activate Disaster Recovery Support

To start DR services on the quad, activate disaster recovery services on the DRleader (Production-A) using the dr-activate command.

This command is only available on the DR leader, and will only be successful ifkey-join has been called on the other DR members to establish disaster recoverycommunications.

Rejoining the QuadIf an appliance loses and then regains communications with the quad, no specialactions are required to restore DR activity. However, if an appliance requiresconfiguration changes, there are some steps needed to rejoin the DR cluster.

DR Members

To restore a DR member that required a new setup to the quad:

1. From the CLI, issue the info command to view the appliance configurationsettings. Ensure that the DR member has the appropriate DR configurationsettings for its role. See Task A, Initial Setup, for more information.

2. On the DR leader (Production-A), issue the key-accept command.

3. On the DR member rejoining the quad, issue key-join.

4. On the DR leader (Production-A), issue key-accept off.

5. Depending on whether the joining DR member is a production or backupappliance, enable or disable EMS services.

— If the joining member is a backup site appliance (either Backup-A orBackup-B), issue:services all disable perm

— If the joining member is Production-B, issue:services all enable

DR Leader

Because the DR leader owns the DR keys, it cannot leave the DR cluster unless itloses its keys. This only happens in the event of a DR scenario. See Restoring theProduction Site on page 41 for details.



Recovering to a Backup SiteIn the event of a production site failure, you manually activate the backup site. Torecover to the backup site, issue the dr-recover command at the backup site.

Recovering from a disaster only requires one appliance be available at the backupsite. The full quad is required to setup the DR feature, but not to recover from aDR event. For example if one of the appliances at the backup site is down forrepair, you can still recover to the available appliance.

• If both Backup-A and Backup-B are available, OR if only Backup-A isavailable, then issue dr-recover on Backup-A.

• If only Backup-B is available, issue dr-recover from Backup-B.

dr-recover erases all prior data from the backup site and overwrites it with thedata from the production site snapshots.

Restoring the Production SiteAfter a DR event, you restore the production site to operation manually.

1. Bring the appliances at the production site back on line and make sure they'reproperly configured.

If the DR leader (Production-A) has been rebuilt and must re-join the cluster:

a. Run dr-config using same setup and DR parameters as the originalconfigured.

b. On Backup-A issue key-accept.

c. On production-A issue key-join.

d. On Backup-A issue key-accept off.

2. Ensure that each pair of appliances in the quad is properly set-up as an FT pairand has re-joined the cluster, if necessary.

From the CLI for each appliance, issue the info command to view theappliance configuration settings. See Task A, Initial Setup, for moreinformation.

3. At the backup site, issue the dr-restore command. This command restoresactivity at the production site and reestablishes DR processes. Thedr-restore command is only active on the Backup site appliances and isnormally issued from Backup-A.


| 43

Chapter 4 Commands

The TIBCO Enterprise Message Service Appliance command line interface (CLI)is the interface to the software that you use whenever you access the system—whether from the console or through a remote network connection. The CLI,which automatically starts after the system finishes powering up, providescommands that you use to perform various tasks, including starting and stoppingthe EMS server instance, monitoring the system state, and accessing server filesand logs.

Topics

• CLI Overview, page 44

• Command Overview, page 46

• General Commands, page 49

• Disaster Recovery Commands, page 56

• Configuration Setup Commands, page 59


44 | Chapter 4 Commands

CLI Overview

The TIBCO Enterprise Message Service Appliance CLI is a text-based interface forsetup and management of the appliances.

The tibadm user can access the CLI through either a console connection to thesystem or through a Secure Shell (SSH) connection.

To access the appliance using SSH, login using the IP address specified duringsetup and initialization. Depending on the appliance configuration, this may be:

• The management IP address. This is the default setting.

• The EMS Server IP address. This address is used only if the optional EMSServer Gateway was configured and is operational.

See Initializing the Software on page 14 for information on initialization.

Some of the CLI commands are specifying an action on a particular EMS serverinstance. You are therefore required to identify the desired server instance, either0 or 1. In a single appliance configuration, the instance is always 0.

Using the CLI to Make Configuration ChangesThe CLI offers a way to make some changes to the TIBCO Enterprise MessageService Appliance configuration.

To prevent inadvertant changes, commands that modify the applianceconfiguration are not availble through the main CLI interface. To access thesecommands, you must enter the TIBCO EMS Appliance Setup Interface, andexplicitly save and apply changes made while in that interface.

1. From the CLI, issue the setup-enable command to enter the TIBCO EMSAppliance Setup Interface.

2. Make the desired configuration changes using the available commands. SeeConfiguration Setup Commands on page 59 for more information.

3. Issue the config-save command to save the changes made.

In a fault tolerant configuration, some CLI commands act only on the appliancethe CLI is running on. Commands that take an instance parameter do not writechanges to the EMS server instance on the fault tolerant peer. If you specify aninstance number that is not primary for this appliance, the command acts on thesecondary EMS server instance.


CLI Overview | 45

4. Issue the config-apply command to apply the changes.

5. Use the exit or quit command to exit the TIBCO EMS Appliance SetupInterface and return to the main CLI interface.



Command Overview

Table 7 CLI Commands

Command Brief Description See Page

General Commands

exit Exit the current CLI interface. 49

export Export the specified files to the transfer directory. 49

export-support-logs Export configuration and log files for use by TIBCOSupport.

50

forcestart Activate the EMS server instance as a standalone server. 50

halt Shut down all system services in preparation forpowering off the appliance.

50

help Display help information. 50

import Move a file from the file transfer directory to theoperating directory.

51

info Display the state of the EMS server instance. 51

log-show Display the last 50 lines of a log file. 51

quit Exit the current CLI interface. 49

reboot Stop and restart all services and processes on the EMSappliance.

52

restore-primary-active Make the default primary EMS servers active on eachpeer.

52

services Start, stop, or list EMS and DR services on an appliance. 52

setup-enable Initiate a TIBCO EMS Appliance Setup Interface session. 53

setup-show Print a list of the currently applied appliance setupparameters.

53

show Print a list of files of the type specified. 53


Command Overview | 47

start Starts EMS servers. 54

stop Stop running EMS server instance(s). 54

upgrade-software Install a TIBCO Enterprise Message Service Appliancesoftware upgrade package.

54

version-show Print the version numbers for the software componentsof the TIBCO Enterprise Message Service Appliance.

55

Disaster Recovery Commands

dr-activate Activate a previously-configured DR quad. 56

dr-recover Activate the backup site after a DR event. 56

dr-restore Bring the production site back online and reestablishnormal backup operations after an event.

57

key-accept Allow DR members to fetch the DR key from the DRleader.

57

key-join Cause a DR member to request the DR key from the DRleader.

58

key-reset Push a new DR key from the DR leader to members. 58

Configuration Setup Commands

config-apply Apply all saved and pending configuration changes. 59

config-pending Display a list of saved but unapplied configurationchanges.

59

config-revert-pending Remove pending (saved but not applied) configurationchanges.

59

config-revert-unsaved Remove unsaved configuration changes. 60

config-review Display a list of all configuration changes that havebeen made but not saved.

60

config-save Save (but not apply) changes made during the currentsession.

60





dr-config Add or change DR configuration information. 60

ems-config Add or change EMS configuration parameters. 61

ft-config Add or change fault tolerance configuration parameters. 61

hostinfo-config Change host configuration parameters. 61

mgmt-config Change management port configuration parameters. 61

set-timezone Set a new time zone for the appliance. 62

syslog-config Supply the IP address for a remote syslog collector andsend important log messages to the collector.

62




General Commands | 49

General Commands

exitexit

This command exits the current CLI menu.

If you are at the CLI main menu, the command logs the user out and exits the CLI.If you are in a sub-menu, such as the Setup Interface that is accessed using thesetup-enable command, then the exit command returns you to the main CLImenu.

quitquit

This command exits the current CLI menu.

If you are at the CLI main menu, the command logs the user out and exits the CLI.If you are in a sub-menu, such as the Setup Interface that is accessed using thesetup-enable command, then the quit command returns you to the main CLImenu.

exportexport instance logs|cores|certs|config

This command places all files of the specified type into the file transfer directory,where they can be accessed by the tibfile user:

• logs — copies all log files.

• cores — moves any core reports. Note that this removes the core files fromthe operating directory.

• certs — copies the current SSL certificate files.

• config — copies the EMS server instance tibemsd.json configuration file.This also copies the instance-specific tibemsd.config and emsd.pathmap

files, as well as the appliance-wide emsa_params.json andemsa_emsmon.config files.

The appliance-wide files are copied regardless of the instance specified.



export-support-logsexport-support-logs [options]

Create and export a compressed .gz file containing configuration and log files anddebug information to be used by TIBCO Support in the event of a supportrequest. The exported file is placed in the /system/export directory under thetibfile user's home. TIBCO Support will provide additional direction if anyoptions are needed.

forcestartforcestart

This command forces the EMS server instances on the fault tolerant pair ofappliances to transition from the wait-for-peer to active-standalone state. Whenactivated, the EMS server begins serving clients even when its fault tolerant peeris not available.

Before you can use this command, the appliance must be in a wait-for-peer

state. For details on states, see EMS Server States on page 26.

Under normal circumstances, an EMS server instance starts automatically whenthe appliance is powered on. However, the server instance will not start if theappliance is unable to synchronize with its peer.

This command is used to activate an EMS server instance in a fault tolerant pairwhen the connection to the other appliance is unavailable. This command shouldonly be used to activate an EMS server instance when the other machine in thefault tolerant pair cannot be made available and this machine is in thewait-for-peer state. If the fault tolerant pair is in any other state, this commandwill not be accepted. Furthermore, this skips any file synchronization between thetwo machines, resulting in the loss of any new data on the peer.

halthalt

Stops all EMS services and prepares the appliance to be powered off.

helphelp [command]

Display help information.

Enter help for a summary of all available commands.

Enter help command for help on a specific command.



importimport instance certs

Copies the SSL certificate files from the file transfer directory to the operatingdirectory for the specified EMS server instance. Any existing SSL certificates areoverwritten.

instance must be either 0 or 1.

See the section Working with the File Transfer Directory on page 23 for detailsabout files in the file transfer directory.

infoinfo [instance]

Retrieves the state of the EMS server instance on the local appliance and prints thelatest operator notification. For information on possible appliance states, see EMSServer States on page 26.

If an instance is not specified, the info command prints a summary status of allinstances.

If specified, instance must be either 0 or 1.

log-showlog-show instance log-name

This command allows you to view the last 50 lines of a log file on the console.

instance must be either 0 or 1. log-name is the name of the desired log file. Any logfile reported using the show instance logs command can be specified. For thoselogs that are not instance specific (as identified in the output of the showcommand), either instance number may be specified.

For example:

EMS CLI> log-show 0 cli.log

Note that you can still export and download the full log file, if desired.

In a fault tolerant configuration, an import should be issued on both appliances,so that they both have the same resulting configuration.



rebootreboot

Shut down and then restart all services and processes on the appliance.

This command can be used at any time to restart the TIBCO Enterprise MessageService Appliance.

restore-primary-activerestore-primary-active

Transitions a fault tolerant pair of appliances so that the original primary activeservers become active again. This is done when maintenance or a fault of somekind has caused a failover and one appliance is active for both instances.

servicesservices group action [perm]

This command starts, stops, restarts, or lists the services running on an appliancewithout affecting the state of the appliance itself.

group can be:

• mon — applies to all EMS server and related processes, including monitoringprocesses.

• dr — applies to the disaster recovery synchronization service.

• all to include all configured services on the appliance.

action can be:

• enable to start sevice(s).

• disable to stop service(s).

• restart to stop and then restart the service(s).

• list to list the service status.

When action is enable or disable, the optional perm attribute causes the new stateto be preserved across appliance reboots. If perm is not included, the currentdefault service state is used upon reboot.

This command causes the EMS server instance to drop all client connections andforce them to reconnect to the other appliance. This command only succeedswhen both EMS instances on the pair of appliances are in a replicating state.



This command is used to:

• Shutdown services on a DR backup site after testing, and prior to DRactivation.

• Shutdown services on an appliance in preparation for support and/ormaintenance activites.

setup-enablesetup-enable

This command initiates a TIBCO EMS Appliance Setup Interface session. While inthe TIBCO EMS Appliance Setup Interface, you may make modifications to theappliance configuration parameters.

For more information, see Using the CLI to Make Configuration Changes onpage 44.

setup-showsetup-show

Prints a list of significant appliance setup parameters and their values. Theseparameters were configured during the software initialization, and may havebeen modified in a TIBCO EMS Appliance Setup Interface session. See Initializingthe Software for a list of parameters.

showshow instance logs|certs|cores

Prints a list of files of the specified type for the EMS server instance. The list alsoincludes logs that are related to both instances. That is, logs that are notinstance-specific are included in the list.

The list will first contain the logs for the specified instance, and then those logsthat are not instance specific.

• logs — prints a list of log files.

• certs — prints a list of SSL certificate files.

• cores — prints a list of core reports, if any exist. Note that core reports are notinstance-specific.




startstart scope

where scope is either local or ft-pair.

This command starts the EMS server instances on the appliance or on a faulttolerant pair of appliances.

If the scope is local, both EMS server instances on the local appliance are started.If the scope is ft-pair, all EMS server instances on both appliances in the faulttolerant pair are started.

stopstop scope

where scope is either local or ft-pair.

This command stops the running EMS server instances on the appliance(s).

If the scope is local, EMS server instances are stopped for the local appliance. Ifthe scope is ft-pair, all EMS server instances on both appliances in the faulttolerant pair are stopped.

upgrade-softwareupgrade-software file-name

where file-name is the name of the software package to be installed.

Installs a TIBCO Enterprise Message Service Appliance software upgrade that hasbeen previously uploaded to the file transfer directory by the tibfile user.

This command assumes that the upgrade will be applied to both appliances in afault tolerant pair. To upgrade the software:

1. As the tibfile user, upload the software package to each machine by way ofSFTP. The package must be added to the /system/import directory. Fordetails, see Working with the File Transfer Directory on page 23

To view the contents of a file, use the export command to copy or move the filesto the file transfer directory, then retrieve the files using the tibfile user.

To tail the last 50 lines written to the log file, use the log-show command.



2. In the CLI for the primary appliance, issue the upgrade-software command,specifying the uploaded package name. For example, where the softwarepackage is named TIB_emsa_2.1.0_illumos11_x86_64.pkg:EMS CLI> upgrade-software TIB_emsa_2.1.0_illumos11_x86_64.pkg

This command stops the EMS server instances on the appliance, applies theupdate, and reboots the machine in wait-for-peer state.

3. In the CLI for the secondary appliance, issue the same upgrade-softwarecommand, specifying the software package name.

The command stops the EMS server instances, applies the update, and rebootsthe machine. The pair then synchronizes and resumes activity.

version-showversion-show instance

Prints the version numbers for the software components of the TIBCO EnterpriseMessage Service Appliance, including the Pluribus operating system software,the EMS Appliance CLI version, and the EMS Appliance State Machine version.


If you are using Central Administration to configure the EMS server on yourappliance, then after completing the upgrade you must also refresh the serverinstances in Central Administration. Refresh the EMS server instances aftermigrating the EMS Appliance to the latest release, and before making anyconfiguration change or deployment.



Disaster Recovery Commands

dr-activatedr-activate

Issue this command on the DR leader to active disaster recovery backup serviceson a quad of appliances.

This command is only available on the DR leader, and will only be successful ifkey-join has already been called on the other DR members to establish disasterrecovery communications. The dr-activate command does the following:

• Pushes the DR configuration information and DR key from the DR leader toDR members.

• Establishes communications with all DR members.

• Disables instance services at the backup site.

• Enable the data synchronization service for each EMS server instance on theproduction site appliances.

See Enabling Disaster Recovery on page 39 for more information aboutconfiguring disaster recovery.

dr-recoverdr-recover

The dr-recover command is normally executed from the Backup-A appliance,but in the event that Backup-A is off-line, may be issued from Backup-B. Thiscommand will only be successful if the production site is inactive or unreachable.

When called, dr-recover does the following:

1. Verify the production site is inactive.

2. Verify connectivity to Backup-B.

3. Synchronize with the most recent snapshot from the production site.

Synchronization erases all prior data from the backup site and overwrites itwith the data from the production site snapshot.

4. Synchronize with Backup-B.

5. Activate EMS services.

6. Verify that EMS instances on Backup-A and Backup-B are fully operational.


Disaster Recovery Commands | 57

Should one of the Backup appliances also be down, the available backupappliance can be recovered in single appliance recovery mode.

dr-restoredr-restore [-force]

This command restores activity to the production site and reestablishes DRbackup processes following a DR scenario. The dr-restore command is activeonly on the Backup site, and is normally issued from Backup-A. However, ifBackup-A is unavailable, you can issue the command from Backup-B byspecifying the -force flag.

When called, dr-restore does the following:

1. Verifies connectivity within the quad.

2. Deactivates EMS server instances on the production appliances, if any arerunning.

3. Deactivates EMS server instances on the backup appliances, if any arerunning.

4. Generates final file system snapshots on the backup site appliances.

5. Pushes snapshots to the Production site appliances.

6. Starts EMS services.

7. Verify that EMS instances on Production-A and Production-B are fullyoperational.

For more information, see Restoring the Production Site on page 41.

key-acceptkey-accept [off]

This command allows DR members joining the quad to fetch the DR key. Thecommand is only available on the DR leader (generally Production-A).

The optional off argument can be used to complete the keying sequence when anappliance needs to rejoin a running cluster. When included, the off argumentterminates access to the public key and push key and DR information toconnected and configured DR members. Note that key-accept off is not neededif the dr-activate command is used.



key-joinkey-join

This command causes a DR member to request the DR key from the DR leader.

key-resetkey-reset

This command pushes a new DR key from the DR leader to DR members. The DRmembers must have already joined before key-reset is issued. (That is, thiscommand cannot be used unless key-accept and key-join have already beenissued.)


Configuration Setup Commands | 59

Configuration Setup Commands

The commands listed here can be used to make changes to the configuration ofthe TIBCO Enterprise Message Service Appliance. Before you can access thesecommands, you must initiate a TIBCO EMS Appliance Setup Interface sessionusing the setup-enable command.

For details, see Using the CLI to Make Configuration Changes on page 44.

config-applyconfig-apply

This command applies all pending configuration changes that have been saved inthe current or a previous TIBCO EMS Appliance Setup Interface session. Ifchanges were made to the fault tolerance or EMS server settings with ft-config

or ems-config, issuing config-apply causes the affected EMS server instance torestart.

Before applying configuration changes, you must save them using theconfig-save command.

config-pendingconfig-revert-pending

Prints a list of saved (but not yet applied) configuration changes.

The changes listed here will be applied when the config-apply command isissued.

config-revert-pendingconfig-revert-pending

The command causes the appliance to discard all configuration changes that havebeen saved but not yet applied.

Only changes that are listed by the config-pending command are discarded.Changes that have not been saved are not affected by this command.



config-revert-unsavedconfig-revert-unsaved

The command causes the appliance to discard all configuration changes that havenot been saved.

Only changes that are listed by the config-review command are discarded.Changes that have been saved are not affected by this command.

config-reviewconfig-review

This command shows all configuration changes that have been made but notsaved. Changes listed will be saved when the config-save command is issued.

config-saveconfig-save

This command saves, but does not apply, all changes that have been made duringthe TIBCO EMS Appliance Setup Interface session. The command affects allchanges that are listed by the config-review command.

dr-configdr-config

If you initialized the software for an appliance without enabling disaster recovery,or if you would like to change your disaster recovery configuration settings, usethis command to set up disaster recovery information.

For an explanation of the prompts that follow this command and their settings,see Configure Disaster Recovery on page 19. For details about enabling andactivating disaster recovery, see Enabling Disaster Recovery on page 39.

Unsaved changes are persisted until the current CLI session ends. Even if you exitthe Setup Interface, unsaved changes are still available to be saved if you reenterit. When you exit the main CLI session, all changes are discarded.

If DR is already active, services should be disabled prior to changing theconfiguration.

After making configuration changes, such as entering a new IP address, you mustre-run the key-accept, key-join, and dr-activate commands.


Configuration Setup Commands | 61

ems-configems-config

Use this command to change the EMS server configuration that was specifiedduring software initialization.

For an explanation of the prompts that follow this command and their settings,see Configure EMS Server Information on page 17.

ft-configft-config

If you initialized the software for an appliance without enabling fault tolerance, orif you would like to change your fault tolerant configuration settings, use thiscommand to set up the appliance.

For an explanation of the prompts that follow this command and their settings,see Configure Fault Tolerant Behavior on page 18.

hostinfo-confighostinfo-config

Use this command to change generic host information, such as DNS servers. Foran explanation of the prompts that follow this command and their settings, seeConfigure Host Information on page 16.

mgmt-configmgmt-config

Use this command to change management interface networking parameters. Foran explanation of the prompts that follow this command and their settings, seeConfigure Management Information on page 15.

If you make changes to the configuration of a server in a fault tolerant pair, youmust also make change to its peer using the ft-config command. If theappliance settings are not in sync, the EMS servers will not be able to connect aftera restart.

If you make changes to the configuration of a server in a fault tolerant pair, youmust also make change to its peer using the ems-config command. If theappliance settings are not in sync, the EMS servers will not be able to connect aftera restart.



set-timezoneset-timezone [time-zone]

Sets a new time zone, as specified by time-zone. If no time-zone is specified, or iftime-zone is not a recognized time zone, the command-line enters an interactivemode which prompts you through the time zone selection process.

Specify the time zone by entering a time zone name from the tz database. Forexample, America/New_York or US/Eastern are both valid settings. Lists of timezone names are available online:http://en.wikipedia.org/wiki/List_of_tz_database_time_zones.

syslog-configsyslog-config

This command configures the appliance to transmit important log messages to aremote syslog daemon, commonly known as a collector. Only messages of prioritywarning and higher are transmitted to the collector.

When entered, syslog-config returns the prompt:

Enter the IP address where syslog messages will be sent ():

Enter the IP address where the collector is located to begin transmitting logmessages.

Note that the syslog-config command does not stop the default loggingbehavior. Even after this command is called, the appliance continues to write logmessages of all levels to a local log file.

This command is saved and applied immediately, without need to issue theconfig-save or config-apply commands. However, the appliance must berebooted before the new time zone setting takes effect.



TIBCO Enterprise Message Service Appliance Installation ...

Documents

Transcript of TIBCO Enterprise Message Service Appliance Installation ...