TIBCO FTL Administration

Transcription

TIBCO FTL®
Administration
Software Release 4.1
July 2014
Two-Second Advantage®
Important Information
SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED
OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED
ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED
SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR
ANY OTHER PURPOSE.
USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A
LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE
AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER
LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE
SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE
LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED
IN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS
AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN
AGREEMENT TO BE BOUND BY THE SAME.
This document contains confidential information that is subject to U.S. and international copyright laws and
treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO
Software Inc.
TIBCO, Two-Second Advantage, The Power of Now, TIB, Information Bus, FTL, eFTL, Rendezvous and
Messaging Appliance are either registered trademarks or trademarks of TIBCO Software Inc. in the United
States and/or other countries.
Enterprise Java Beans (EJB), Java 2 Platform Enterprise Edition (J2EE), and all Java-based trademarks and logos
are trademarks or registered trademarks of Oracle Corporation in the U.S. and other countries.
All other product and company names and marks mentioned in this document are the property of their
respective owners and are mentioned for identification purposes only.
THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL
OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME
TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC
OPERATING SYSTEM PLATFORM.
THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
IMPLIED, 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 BE
INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE
IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN
THIS DOCUMENT AT ANY TIME.
THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR
INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING
BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.
Copyright © 2010–2014 TIBCO Software Inc. ALL RIGHTS RESERVED.
TIBCO Software Inc. Confidential Information
| iii
Contents
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xv
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xx
TIBCO FTL Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xx
TIBCO eFTL Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxi
Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
Connecting with TIBCO Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to Join TIBCOmmunity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to Access All TIBCO Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to Contact TIBCO Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xxv
xxv
xxv
xxv
Chapter 1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1
Product Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Brief Definitions of Key Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Messaging Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Infrastructure Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Administrative Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Realm Definition Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Realm Administration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Chapter 2 Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
Formats—Managed, Built-In and Dynamic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Manage All Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Defining Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Catalog of Built-In Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Chapter 3 Implementing Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
Configuration Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Abilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
iv
| Contents
Abilities in the Configuration Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Implementation—Endpoints (Micro) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Connectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Connectors to Cover Abilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
20
20
20
21
Implementation—Application (Macro) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Application Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Application Instance Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Default Instance and Named Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Matching Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Result: Instance Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Subscribers and Durables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
23
23
24
25
25
26
26
Administrative Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Administrative Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transport Type and Abilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transport Type and Host Computer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Segregating Traffic by Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Multiple Transports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
28
28
28
28
28
Sample Configuration 1—tibsend and tibrecv. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Sample Configuration 2—tibrequest and tibreply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Chapter 4 Transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Transport Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transport Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Inside a Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transport Definitions Must be Unique . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
36
36
36
37
Unitary and Fragmentary Transport Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Transport Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Bus Topologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Unitary Mesh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assembling Larger Topologies from Pair Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Asymmetric Multicast Topologies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
40
40
40
42
Pair Connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Listen End and Connect End . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Connect Requests are Specific to IP Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Subscriber Interest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Blocking vs Non-Blocking Send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Shared Memory Transports and One-to-Many Non-Blocking Send. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Blocking Send and Inline Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Inline Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Receive Spin Limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Contents v
|
Motivation and Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Tuning Receive Spin Limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
From Transports to Dispatch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
UDP Packet Send Limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Shared Memory Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Non-Blocking Send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Remote Direct Memory Access Transport (RDMA) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
RDMA Hardware. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
RDMA Implementation Libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Locked Memory Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Dynamic TCP Transport. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Static TCP Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Multicast Transport (Mcast) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Multicast Group as Shared Communication Medium . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Configuring Multicast Inbox Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Multicast Retransmission Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Reliable UDP Transport (RUDP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Process Transport (PROC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Chapter 5 Realm Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
Realm Server Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Affiliated Realm Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Server Roles and Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Modifying the Realm Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Configuring Fault Tolerance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Configuring Satellites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Realm Server Authentication and Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Password File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
JAAS Sample Login Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Option and Property Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Using the tibrealmserver Executable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Using the tibrealmadmin Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
vi
| Contents
Chapter 6 Realm Server and its Browser Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Browser Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Realm Server URL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Common Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Home Logo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Command Icons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Auto-Save . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
99
99
99
99
99
Realm (Home Page) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Sidebar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Navigating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Status Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Summary Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Viewing an Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Filtering the List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sorting the List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a New Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Duplicating a Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deleting a Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
106
106
106
106
107
107
107
Restrictions on Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Reserved Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Length Limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Size Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Realm Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Modification Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Lock & Edit Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Refresh and Revert Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
The Deploy Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transaction Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Responses to Deployment Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Consolidating Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Satellite Servers Recursively Test Their Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Successful Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Unsuccessful Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Backup Prevents Satellite Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
112
112
113
113
113
114
114
114
Valid Realm Modifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Chapter 7 Configuring a Realm using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Applications Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Configuring an Application Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Contents vii
|
Configuring an Application Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Transports Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Configuring a Transport Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Edit Configuration Manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Formats Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Show Historic Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Configuring a Format Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Configuring the Realm Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Restricting Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Chapter 8 Browsing a Realm using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143
Validation Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Instance Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Connections at Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Understanding the Instance Connections Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Visualizing Specific Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Filtering Instance Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Transport Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Realm Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Chapter 9 Monitoring a Realm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Monitoring the Realm Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Clients Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Monitoring a Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Dynamic TCP Transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Client Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Disabling Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Satellites Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Satellite Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Deployment Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Active Deployment Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
New Clients during a Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Last Deployment Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Recent Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Redeploy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
viii
| Contents
Chapter 10 Configuring a Realm using Python Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Using the Realm Server Python Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Chapter 11 Client Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Sampling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Estimating Maximum Memory Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Catalog of Client Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Standard Client Statistics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Client Statistics for Multicast Transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Store Server Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
184
184
185
186
Web API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Chapter 12 Rendezvous Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Adapter Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FTL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Rendezvous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
192
192
192
193
Adapter Operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Start Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FTL Side . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Rendezvous Side. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
194
194
194
195
Using tibrvadapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Password File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Disabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Adapter Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Adapter Administration—Realm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Communication through Transports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Bidirectionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
One-to-One Abilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
204
204
204
204
Adapter Subject Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Parsing a Rendezvous Subject to FTL Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Assembling FTL Fields to a Rendezvous Subject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Adapter Datatype Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FTL to Rendezvous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Rendezvous to FTL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
206
206
207
208
Contents ix
|
Request/Reply Interactions through the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Primary FTL Request, Secondary Rendezvous Reply to an Inbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Secondary Rendezvous Request to an Inbox, Tertiary FTL Reply. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Primary Rendezvous Request to a Subject, Secondary FTL Reply to an Inbox . . . . . . . . . . . . . . . . . . . . . 211
Rendezvous Subjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Messages that Match Two Rendezvous Subjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Chapter 13 Groups of Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .215
Administrative Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
Group Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
Running the Group Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
Fault Tolerance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Using the Group Setup Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Disabling Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Group Server Monitoring Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Chapter 14 Transport Bridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .221
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Design Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Latency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Shifting Fanout for Efficiency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Extending the Capabilities of a Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Multiple Transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Crossing the Boundary of Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
Isolated Spokes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Topologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
One Bridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
Two Serial Bridges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
Hub and Spoke Bridges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Transport Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Configuring Bridges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Adding Bridge Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Use Transports Uniquely . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Using the Transport Bridge Executable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Password File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Fault Tolerance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Shared Memory Transports and Fault-Tolerant Bridges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
x
| Contents
Bridges among Dynamic TCP Meshes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Principles of Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Bridge Setup Script for Dynamic TCP Meshes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
Deleting a Bridge Definition for Dynamic TCP Meshes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Adding Satellites to a Bridge for Dynamic TCP Meshes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Bridges Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
Configuring a Bridge Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Bridge Monitoring Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Bridge Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Bridge Setup Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Chapter 15 Persistence (Stores and Durables) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Feature Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Architecture for Delivery Assurance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Architecture for Apportioning Message Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Coordination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
251
251
251
252
252
Stores for Delivery Assurance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Topology. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Retention and Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Larger Networks of Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Combined Message Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Multiple Stores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Violating the Direct Path Requirement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Durable Collision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Default Durable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
253
253
253
254
255
255
257
258
258
Stores for Apportioning Message Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Topology. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Apportioning. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Acknowledgment and Redelivery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
259
259
259
259
Persistence Servers and Cluster. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Quorum and Leader. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Quorum Conditions—General Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Cluster Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Quorum Behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Fault Tolerance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
260
260
260
261
261
262
Realm Configuration Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Persistence Server Transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Alternate Client Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Client Transport and Non-Blocking Send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Publisher Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Contents xi
|
Durable Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Shared or Non-Shared . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Acknowledgement Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Message Interest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Configuring the Realm Persistence Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Cluster Heartbeat and Timeout Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Configuring a Persistence Server Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Configuring a Store Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Configuring a Durable Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Configuring Persistence Stores within the Application Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Configuring Durable Subscribers within an Application Instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Matching Instances for Subscriber Name Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Configuring a Default Durable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Persistence Servers Monitoring Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Forcing a Quorum. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Monitoring a Persistence Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Persistence Server Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Persistence Stores Monitoring Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Monitoring a Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Durables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Monitoring a Shared Durable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Shared Durable Subscribers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Starting a Persistence Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Stopping a Persistence Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
tibstore Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Saving and Loading Persistence State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Purging Durables or Stores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Purging a Durable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Purging a Store. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Chapter 16 Package Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .303
Directory Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Appendix A Coordination Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .307
Application Coordination Form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Endpoint Coordination Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Format Coordination Form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Durable Coordination Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
xii
| Contents
Appendix B Upgrade Migration to a New Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
Upgrading Realm Servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Upgrading tibstore Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Appendix C FTL Processes as Windows Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Installing a Persistence Server as a Windows Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Installing a Transport Bridge as a Windows Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Installing the Realm Server as a Windows Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Uninstalling a Windows Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Figures xiii
|
Figures
Figure 1
Connectors Cover Endpoint Abilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Figure 2
Application Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Figure 3
Transports and Bus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Figure 4
Related Transports—Data Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Figure 5
Unitary Mesh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Figure 6
Hub and Spoke Topology. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Figure 7
Mesh Topology for Connection-Oriented Transport Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Figure 8
Asymmetric Multicast—Bipartite Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Figure 9
Receive Spin Limit—Example with Several Transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Figure 10
Affiliated Realm Servers: Roles and Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Figure 11
Realm Storage and Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Figure 12
Application Instance Connections Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Figure 13
Application Instance Connections Graph with Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Figure 14
Application Instance Connections Graph, Highlighting Specific Connections . . . . . . . . . . . . . . . . 149
Figure 15
Rendezvous Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Figure 16
Fanout over WAN (without Transport Bridge) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Figure 17
Transport Bridge: Fanout after WAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Figure 18
Transport Bridge: Extending Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Figure 19
Transport Bridge: Connecting Shared Memory on Two Computers . . . . . . . . . . . . . . . . . . . . . . . 226
Figure 20
Transport Bridge: Common Hub with Mutually-Isolated Spokes . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Figure 21
Transport Bridge Topology—One Bridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
Figure 22
Transport Bridge Topology—Two Bridges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
Figure 23
Transport Bridge Topology—Hub and Spoke Bridges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Figure 24
Bridging for Dynamic TCP Meshes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Figure 25
Store as Redundant Message Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Figure 26
Store for Message Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Figure 27
Store Serves Several Publishers and Subscribers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Figure 28
Two Stores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
xiv
| Figures
Figure 29
Two Stores with Many Publishers and Subscribers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Figure 30
Erroneously Using One Store Instead of Two . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Figure 31
Store as Apportioning Intermediary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Figure 32
Configuring Durables in an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Figure 33
Store Servers—Forcing a Quorum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Tables xv
|
Tables
Table 1
General Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
Table 2
Syntax Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii
Table 3
Built-In Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Table 4
Endpoint Abilities—Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Table 5
Endpoint Abilities—Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Table 6
Sample Configuration—tibsend and tibrecv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Table 7
Sample Configuration—tibrequest and tibreply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Table 8
Listen End and Connect End . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Table 9
Blocking and Non-Blocking Send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Table 10
Transport Configuration Parameters: Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Table 11
Transport Configuration Parameters: RDMA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Table 12
RDMA Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Table 13
RDMA Driver Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Table 14
Transport Configuration Parameters: Dynamic TCP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Table 15
Transport Configuration Parameters: Static TCP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Table 16
Transport Configuration Parameters: Multicast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Table 17
Transport Configuration Parameters: RUDP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Table 18
Transport Configuration Parameters: PROC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Table 19
Affiliated Realm Servers—Role Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Table 20
Configuring JAAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Table 21
tibrealmserver Utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Table 22
tibrealmadmin Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Table 23
Realm Server Browser Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Table 24
Realm Server Icons—Configure and Browse Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Table 25
Realm Server Icons—Maniupulating Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Table 26
Realm Server Icons—Monitoring Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Table 27
Status Summary (Sidebar) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Table 28
Filtering Instance Connections—Regular Expression Semantics . . . . . . . . . . . . . . . . . . . . . . . . 106
xvi
| Tables
Table 29
Size Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Table 30
Responses after Testing a Modified Realm Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Table 31
Action Status Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Table 32
Realm Modifications and Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Table 33
Application Definition—Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Table 34
Application Instance Definition—Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Table 35
Transport Definition—Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Table 36
Format Definition—Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Table 37
Field Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Table 38
Realm Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Table 39
Realm Configuration Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Table 40
Instance Connections Graph, Iconography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Table 41
Filtering Instance Connections—Regular Expression Semantics . . . . . . . . . . . . . . . . . . . . . . . . . 149
Table 42
Filtering Instance Connections—Display Modifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Table 43
Server Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Table 44
Clients Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Table 45
Client Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Table 46
Satellites Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Table 47
Satellite Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Table 48
Deployment Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Table 49
Active Deployment Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Table 50
Recent Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Table 51
Realm Server Python Scripts and Related Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Table 52
Client Monitoring Resource Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Table 53
Client Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Table 54
Client Statistics for Multicast Transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Table 55
Monitor API: Monitor Command, Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Table 56
Monitor API: Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Table 57
Monitor API: Client Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Table 58
Monitor API: Series Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Table 59
Monitor API: Data Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Table 60
tibrvadapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Tables xvii
|
Table 61
Configuration Language for Rendezvous Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Table 62
Datatype Mapping: FTL to Rendezvous. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Table 63
Datatype Mapping: Rendezvous to FTL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Table 64
Validating Rendezvous Subjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Table 65
Group Setup Script—Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Table 66
tibbridge Executable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Table 67
init_dtcp_bridge Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
Table 68
Bridge Definition—Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Table 69
Bridges Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Table 70
Bridge Status Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Table 71
init_bridge Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Table 72
Reforming a Quorum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Table 73
Store Publisher Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Table 74
Acknowledgement Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Table 75
Message Interest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Table 76
Persistence Cluster Advanced Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Table 77
Persistence Server Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Table 78
Store Definition—Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
Table 79
Durable Definition—Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Table 80
Persistence Servers Summary—Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Table 81
Persistence Server Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Table 82
Persistence Server Status—Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Table 83
Store Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Table 84
Stores Summary—Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Table 85
Persistence Store Status—Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Table 86
Durable Subscribers Summary—Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Table 87
Durable Status—Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Table 88
Shared Durable Status—Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Table 89
tibstore Command Line Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Table 90
FTL Directories. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Table 91
Files in Samples Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Table 92
Samples Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
xviii Tables
|
Table 93
Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Table 94
Application Coordination Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Table 95
Endpoint Coordination Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Table 96
Format Coordination Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Table 97
Durable Coordination Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
| xix
Preface
TIBCO FTL® is a messaging infrastructure product.
TIBCO is proud to announce the latest release of TIBCO FTL®. This release is the
latest in a long history of TIBCO products that leverage the power of the
Information Bus® to enable truly event-driven IT environments. To find out more
about how TIBCO FTL and other TIBCO products are powered by TIB®
technology, please visit us at www.tibco.com.
Topics
•
Related Documentation, page xx
•
Typographical Conventions, page xxii
•
How to Contact TIBCO Support, page xxv
xx
| Related Documentation
Related Documentation
This section lists documentation resources you may find useful.
TIBCO FTL Documentation
The documentation road map shows the relationships between the books and
online references in this product’s documentation set.
Concepts
Development
Installation
API Reference
C API
Reference
Java API
Reference
Administration
Glossary
.NET API
Reference
Release Notes
Legend
PDF
HTML
The following documents form the FTL documentation set:
•
TIBCO FTL Concepts Everyone reads this booklet first, for an intuitive
introduction to the fundamental concepts of FTL.
•
TIBCO FTL Development Application developers and architects read this
manual to understand concepts relevant in any supported programming
language.
•
TIBCO FTL API Reference Application developers use this HTML
documentation to learn the details of the FTL API in specific programming
languages.
•
TIBCO FTL Administration Administrators read this manual to learn how to
use the realm server and its interfaces, and how to define a realm. Developers
can also benefit from understanding FTL from an administrator’s perspective.
Preface xxi
|
•
TIBCO FTL Installation Read this manual before installing the product.
•
TIBCO FTL Glossary The glossary contains brief definitions of key terms used
in all other parts of the documentation set.
•
TIBCO FTL Release Notes Read the release notes for a list of new and changed
features. This document also contains lists of known issues and closed issues
for this release.
TIBCO eFTL Documentation
TIBCO eFTL™ is documented separately. Administrators use the FTL realm
server GUI to configure and monitor the eFTL service. For information about
these GUI pages, see the documentation set for TIBCO eFTL.
xxii
| Typographical Conventions
Typographical Conventions
The following typographical conventions are used in this manual.
Table 1 General Typographical Conventions
Convention
Use
TIBCO_HOME
Many TIBCO products must be installed within the same home directory. This
directory is referenced in documentation as TIBCO_HOME. The value of
TIBCO_HOME depends on the operating system. For example, on Windows
systems, the default value is C:\tibco.
ENV_HOME
FTL_HOME
USER_HOME
Other TIBCO products are installed into an installation environment. Incompatible
products and multiple instances of the same product are installed into different
installation environments. An environment home directory is referenced in
documentation as ENV_HOME. The syntax of ENV_HOME depends on the
operating system. For example, on Windows systems the default value is
C:\tibco.
TIBCO FTL installs into a directory within TIBCO_HOME. This directory is
referenced in documentation as FTL_HOME. The syntax of FTL_HOME depends
on the operating system. For example, on Windows systems the default value is
TIBCO_HOME\ftl\release_num.
USER_HOME is your home directory. Installation leaves log files and other
artifacts in subdirectories under this location.
code font
Code font identifies commands, code examples, filenames, pathnames, and
output 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 of
particular interest.
•
In command syntax, to indicate the default parameter for a command. For
example, if no parameter is specified, MyCommand is enabled:
MyCommand [enable | disable]
Preface xxiii
|
Convention
Use
italic font
Italic font is used in the following ways:
Key
combinations
•
To indicate a document title. For example: See TIBCO FTL Concepts.
•
To introduce new terms For example: A portal page may contain several
portlets. 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
Key name separated by a plus sign indicate keys pressed simultaneously. For
example: Ctrl+C.
Key names separated by a comma and space indicate keys pressed one after the
other. For example: Esc, Ctrl+Q.
The note icon indicates information that is of special interest or importance, for
example, an additional action required only in certain circumstances.
The tip icon indicates an idea that could be useful, for example, a way to apply
the information provided in the current section to achieve a specific result.
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 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
xxiv Typographical Conventions
|
Convention
Use
{ }
A logical group of items in a command. Other syntax notations may appear
within each logical group.
For example, the following command requires two parameters, which can be
either 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 parameter
can 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 the
second parameter. And the last parameter is either param3 or param4.
MyCommand param1 [param2] {param3 | param4}
Preface xxv
|
Connecting with TIBCO Resources
How to Join TIBCOmmunity
TIBCOmmunity is an online destination for TIBCO customers, partners, and
resident experts, a place to share and access the collective experience of the
TIBCO community. TIBCOmmunity offers forums, blogs, and access to a variety
of resources. To register, go to http://www.tibcommunity.com.
How to Access All TIBCO Documentation
After you join TIBCOmmunity, you can access the documentation for all
supported product versions here:
http://docs.tibco.com
How to Contact TIBCO Support
For comments or problems with this manual or the software it addresses, please
contact TIBCO Support as follows.
•
For an overview of TIBCO Support, and information about getting started
with 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 user
name, you can request one.
xxvi Connecting with TIBCO Resources
|
|1
Chapter 1
Introduction
This chapter introduces the main components and concepts of TIBCO FTL®.
Topics
•
Product Overview, page 2
•
Brief Definitions of Key Concepts, page 3
•
Realm Definition Terminology, page 6
2
| Chapter 1
Introduction
Product Overview
TIBCO FTL is a messaging infrastructure product. It features high speed,
structured data messages, and clearly defined roles for application developers
and application administrators. FTL can achieve low message latency with
consistent performance.
Components
FTL comprises these main components:
•
API libraries—developers use these APIs in application programs
•
Realm server—applications obtain operational metadata from the realm
server
•
Store server—stores messages for durable subscribers
•
Transport bridge—forwards messages between two endpoints
•
TIBCO Rendezvous® adapter—converts messages so FTL programs can
communicate with existing Rendezvous programs
Brief Definitions of Key Concepts 3
|
Brief Definitions of Key Concepts
We recommend that you first read the booklet TIBCO FTL Concepts, which builds
an intuitive picture of FTL software and its concepts.
Messaging Concepts
Application programs use FTL to communicate by sending messages to one
another. Programs send messages using publisher objects, and receive messages
using subscriber objects.
Messages travel directly between peers (application programs) rather than
through a store-and-forward server.
FTL messages travel only among application processes; they do not travel from
publishers to subscribers within a process. A process transport is an explicit
exception to this rule; it carries messages within a process.
Messages and Fields
A message is a structured unit of data. The structure is flexible, and developers
tailor the structure to the needs of the application.
Each message consists of a set of named fields. Each field can contain a value of a
specific datatype.
One-to-Many Communication
Publishers can send messages using one-to-many communication. These messages
can reach potentially many subscribers.
A subscriber can use a content matcher to receive only those messages in which a
particular set of fields contain specific values.
One-to-One Communication
For efficient one-to-one communication, publishers can also send messages that
can reach one specific inbox subscriber.
An inbox is a data structure that uniquely identifies a specific inbox subscriber.
Inbox subscribers cannot use content matchers. An inbox subscriber receives all
messages directed to it.
4
| Chapter 1
Introduction
Infrastructure Concepts
Endpoint
An endpoint is an abstraction that represents a set of publishers and subscribers in
communicating programs. Application architects and developers determine the
set of endpoints that an application requires. Administrators formally define
those endpoints. Programs create publisher and subscriber objects, which
instantiate those endpoints.
Endpoint Abilities
From the perspective of a running application instance, each endpoint carries
messages in up to four abilities. Two dimensions—direction and reach—determine
the set of messages that flow along each ability:
•
Direction: Each ability carries messages in only one of two possible
directions—either inbound to the application’s subscribers, or outbound from
the application’s publishers.
•
Reach: Each ability carries messages from only one kind of send call—either
one-to-many or one-to-one—according to the number of subscribers the message
can potentially reach.
Inbound
Outbound
One-to-Many
Receive
Send
One-to-One
Receive Inbox
Send Inbox
Transport
A transport is the underlying mechanism that moves message data between
endpoint instances in programs. For example, a shared memory transport can
move messages among separate program processes on a multi-core hardware
platform; a multicast transport can move messages among programs connected
by a network.
Stores and Durables
You can use stores and durables to strengthen message delivery assurance or to
apportion message streams among a set of cooperating subscribers. A separate
chapter presents this topic in detail.
Brief Definitions of Key Concepts 5
|
Administrative Concepts
A realm is a namespace that defines resources and configurations available to
application programs. (Those resources include endpoints, transports and
formats.) Administrators use a graphical configuration interface to define the
realm, and store that definition in a realm server. Each process instance of an
application program connects to the realm server to download the part of the
realm definition that is relevant to that instance; the FTL base library caches that
definition in a realm object. After a program caches the realm definition, it is not
necessary to interact frequently with the realm server. The FTL base library
consults the local realm object for information about endpoints, transports and
message formats (see below). It is not necessary to involve the realm server each
time a program sends or receives a message.
Administrators define transports within the realm. Notice that transports are not
visible to application developers—rather, they are strictly the responsibility of the
administrator. From the developer’s perspective, these details are hidden behind
endpoints.
In addition to endpoints, transports and formats, the realm definition also
includes other definitions and configurations:
•
The term application can refer to an executable program that communicates
using FTL, or to an administrative configuration in the realm. Administrators
declare and configure each application, and define the realm resources that
process instances of the application may use.
•
The term application instance can refer either to a process instance of an
application program, or to an administrative configuration in the realm.
Through a matching algorithm, one such configuration can apply to a set of
process instances. When defining a configuration, administrators can assign
different resources to specific sets of process instances (based on attribute
matching), to achieve fine-grained control over communications traffic.
When defining an application instance configuration, the administrator must
connect each application endpoint to one or more transports, which actually
move message data.
The realm definition can also include definitions related to stores and durables
(see Chapter 15, Persistence (Stores and Durables), on page 249).
See Also
These concepts are explained in greater detail in later chapters of this book.
6
| Chapter 1
Introduction
Realm Definition Terminology
Administrators and developers coordinate the detailed requirements of
applications using coordination forms (we recommend printing hardcopy from the
appendix in this book).
Administrators use the information in the coordination forms to configure the
realm definition and its parts:
A format definition determines the field names and field value types that can
appear in messages that use a managed format.
A transport definition configures a transport, including its name, transport type,
parameter values, and relationships to other cooperating transports.
An application instance definition is a configuration that implements endpoints by
associating them with transports.
An application definition determines an application’s endpoints, the configuration
of the application’s process instances, and the subset of message formats available
to the application.
See Also
Chapter 2, Formats, page 9
Chapter 3, Implementing Endpoints, page 15
Chapter 4, Transports, page 35
Realm Administration 7
|
Realm Administration
The realm server is a command-line executable component that stores the realm
definition, and makes it available to client application processes. Graphical
interfaces let administrators configure the realm definition and monitor the client
processes. Command line and Python script interfaces let administrators
configure server behavior.
Administrators start, stop, configure and manage the realm server using
command line executables and scripts (see Chapter 5, Realm Server, page 73).
Administrators define the realm and its parts using a configuration interface (see
Chapter 7, Configuring a Realm using the GUI, page 121), and can examine the
definition using graphical tools (see Chapter 8, Browsing a Realm using the GUI,
page 143). Administrators monitor and manage the realm server’s client
processes using a monitoring interface (see Chapter 9, Monitoring a Realm,
page 155). These interfaces and tools are accessible through a web browser
(connecting to the realm server).
Administrators can also manipulate the realm definition using Python scripts (see
Chapter 10, Configuring a Realm using Python Scripts, page 177).
See Also
Chapter 6, Realm Server and its Browser Interfaces, page 97
8
| Chapter 1
Introduction
|9
Chapter 2
Formats
This chapter presents information about formats.
Topics
•
Formats—Managed, Built-In and Dynamic, page 10
•
Defining Formats, page 12
•
Catalog of Built-In Formats, page 13
10
| Chapter 2
Formats
Formats—Managed, Built-In and Dynamic
A format defines the set of fields that a message can contain. The form of each
message (its field names and their value datatypes) is governed by a format.
FTL supports three broad categories of format, with differing constraints and
performance characteristics.
•
Managed format: Application architects and developers determine the set of
formats that an application needs. Administrators define those formats
globally.
Administrators make managed formats available to an application by
including them as preload formats for the application.
Programs can use these managed formats to compose new messages, or to
unpack inbound messages. A message with a managed format is small and
fast; it does not carry format metadata because that metadata is available to
applications from the realm server.
•
Built-in format: FTL defines a set of highly-optimized formats, which are
defined within the base library and always available to all applications. (No
administrative action is required.)
The performance characteristics of built-in formats are similar to managed
formats; when used properly, a built-in format can outperform a managed
format.
•
Dynamic format: An application implicitly defines a format as it constructs a
message—that is, the sending program dynamically determines the set of
fields and their datatypes as it sets field values.
When a program creates a message, and specifies a format that is neither
built-in nor preloaded, then FTL automatically treats it as a dynamic format.
A dynamic format is less efficient than a managed format because each
message must be self-describing—that is, it necessarily includes its own
format metadata. Expect larger message sizes, slower transmission, slower
processing, and longer field access times.
Dynamic formats are useful for rapid prototyping projects. We recommend
defining the application’s formats as managed formats when the project nears
the production stage.
Formats—Managed, Built-In and Dynamic 11
|
Manage All Formats
For efficiency and for safety, administrators can use the Manage All Formats
parameters to restrict the formats available to some or all of the applications in a
realm. That is, administrators can require that applications use only preload
formats and built-in formats, and prohibit applications from using dynamic
formats.
See Also
Restricting Formats, page 141
12
| Chapter 2
Formats
Defining Formats
Each realm defines the set of formats that its applications can use. Administrators
also regulate the subset of formats available to each application.
1. Coordinate with developers.
The first step is to consult with developers to determine the format
requirements. To begin the discussion, we recommend that the developer
complete the Format Coordination Form on page 315. Then review the forms
together, and modify them to reflect your agreement.
2. Define managed formats in the realm.
Define the managed formats as specified in the final consensus revision of the
coordination forms. Use the configuration interface to define the formats; see
Formats Summary on page 135, and Configuring a Format Definition on
page 136.
3. Preload formats.
When you define the application, add managed formats to the Preload
Formats section. When a suite of application programs must exchange
messages, ensure that each application definition preloads the formats that
the program sends and receives.
The term preload implies that the application loads these formats when it
connects to the realm server. Furthermore, the only managed formats that an
application can use are its preload formats.
The list of preload formats does not affect built-in formats nor dynamic
formats (see below). You need not include built-in formats in the list of
preload formats—built-in formats are always available to all applications.
4. Dynamic formats.
When the message structure and content is highly variable, and applications
cannot determine or limit that content in advance, dynamic formats might be
appropriate.
If developers and administrators agree that the application requires dynamic
formats, and that this will not degrade the performance of other applications
in the realm (for example, by consuming bandwidth) then administrators can
permit dynamic formats; see Restricting Formats on page 141.
See Also
To upgrade dynamic formats to managed formats while an application is
running, see Add formats on page 115.
Before modifying the definition of a managed format, see Add fields on page 116.
Catalog of Built-In Formats 13
|
Catalog of Built-In Formats
Table 3 Built-In Formats
Format Name Constant
Description
TIB_BUILTIN_MSG_FMT_OPAQUE
The message consists of a singleton field of type opaque.
The constant
denotes the
name of that singleton field (the value of the constant is
_data).
TIB_BUILTIN_MSG_FMT_OPAQUE_FIELDNAME
The constant value
TIB_BUILTIN_MSG_FMT_OPAQUE_MAXSIZE is the
maximum data length (in bytes) of a message of this
type. (This size restriction applies only to built-in opaque
formats; it does not apply to opaque fields in other
formats.)
TIB_BUILTIN_MSG_FMT_KEYED_OPAQUE
This keyed opaque format enhances the opaque format
with a key field of type string. Content matchers can
match against the key field.
The constant TIB_BUILTIN_MSG_FMT_KEY_FIELDNAME
denotes the name of the string field (the value of the
constant is _key).
The constant value TIB_BUILTIN_MSG_FMT_KEY_MAXLEN
is the maximum length (in bytes) of the key string field—
including the null terminator character.
The constant
denotes the
name of the opaque data field (the value of the constant
is _data).
TIB_BUILTIN_MSG_FMT_OPAQUE_FIELDNAME
The length of the key (including the null terminator
character) plus the length of the opaque data must be less
than or equal to the constant
TIB_BUILTIN_MSG_FMT_OPAQUE_MAXSIZE. (This size
restriction applies only to built-in opaque formats; it does
not apply to opaque fields in other formats.)
14
| Chapter 2
Formats
| 15
Chapter 3
Implementing Endpoints
Transports carry message data for endpoints. This chapter explains the structures
that administrators use to configure endpoint implementation and transport
usage in the realm.
Topics
•
Configuration Model, page 16
•
Endpoints, page 17
•
Abilities, page 18
•
Implementation—Endpoints (Micro), page 20
•
Implementation—Application (Macro), page 23
•
Administrative Requirements, page 27
•
Administrative Options, page 28
•
Sample Configuration 1—tibsend and tibrecv, page 30
•
Sample Configuration 2—tibrequest and tibreply, page 32
16
| Chapter 3
Configuration Model
This section describes an overarching model. As you read the remainder of this
chapter, the model can serve as a framework for understanding the concepts and
tasks of configuring a realm.
The model is only a skeleton; it is not a complete description. It is not necessary to
completely understand every aspect of the model the first time you read this
section. We recommend returning to this model after reading subsequent sections
to help integrate the new ideas.
•
Endpoints represent requirements.
— Endpoints constitute a program’s communication interface. An application
program with one or more endpoints requires communication through
those endpoints.
— For each of its endpoints, an application program requires communication
using some or all of the endpoint’s four abilities (see Abilities on page 18).
That is, each ability that the program uses for communication is a separate
and specific functional requirement.
•
A connector represents a set of abilities. It binds a transport’s abilities to an
endpoint’s required abilities; when a set of connectors covers all the required
abilities of an endpoint, then the connectors satisfy the endpoint (that is, they
satisfy the requirements that the endpoint represents).
•
An application instance definition represents a solution.
— It implements each endpoint (requirements) with a set of connectors
(abilities)—satisfying the requirement.
— Moreover, it targets a set of process instances. A matching algorithm
dynamically determines that target set.
— You can define several such solutions, each satisfying the same
requirements with different abilities (and targeting a different set of process
instances).
This chapter describes endpoint implementation and its configuration—first at
the micro level (endpoints, abilities and connectors), then at the macro level
(applications and application instances). In practice, administrators generally
configure from both ends inward:
•
Endpoint; transport
•
Application; application instance; connector
Endpoints 17
|
Endpoints
An endpoint is an abstraction that represents a set of publishers and subscribers
in communicating programs.
Within an application program, an endpoint begins as a name. Program code uses
the endpoint name to create endpoint instances—that is, publisher and subscriber
objects. Then programs use the publishers to send messages, and the subscribers
to receive messages.
For many applications (or communicating application suites) a single endpoint
name suffices.
Transports implement endpoints—that is, transports transfer message data from
publishers to subscribers.
Administrators view an endpoint as a complex entity, embracing four separate
abilities (see Abilities on page 18). Administrators define application instances,
with connectors to bind transports to abilities.
Each subscriber object and each call to a publisher send method introduces a
channel requirement. Application developers record these requirements in
endpoint coordination forms. Administrators define connectors within
application instances to satisfy these requirements.
See Also
Endpoint Coordination Form, page 311
18
| Chapter 3
Abilities
Within a program, an endpoint has four communication abilities. A separate
aspect of the API embodies each of these abilities. Each of these four abilities and
its API embodiment corresponds to a distinct sub-stream of messages, called an
ability sub-stream. The following table summarizes the four abilities.
Table 4 Endpoint Abilities—Definitions
Ability
API
Description
One-to-Many Receive
Subscriber object
Carries one-to-many messages inbound to the
endpoint’s subscribers in the application.
One-to-One Receive
Inbox subscriber
object
Carries one-to-one messages inbound to the
endpoint’s inbox subscribers in the application.
One-to-Many Send
Send call
of a publisher object
Carries one-to-many messages outbound from
the endpoint’s publishers in the application.
One-to-One Send
Send-to-inbox call
of a publisher object
Carries one-to-one messages outbound from the
endpoint’s publishers in the application.
Notice that each ability combines two dimensions—reach and direction:
•
Reach
— One-to-many abilities carry messages that can reach potentially many
subscribers.
— One-to-one abilities carry messages that can reach one specific inbox
subscriber.
•
Direction
— Receive abilities carry messages inbound to an application.
— Send abilities carry messages outbound from an application.
Abilities 19
|
Abilities in the Configuration Interface
Table 5 presents these two dimensions in a grid. The grid yields four abilities—
compare the realm server’s graphical configuration interface for configuring a
connector (see Configuring an Application Instance on page 127 and Endpoint
Ability Check-Boxes on page 129).
Table 5 Endpoint Abilities—Summary
Receive
Send
One-to-Many
Receive
Send
One-to-One
Receive Inbox
Send Inbox
In explanatory diagrams, we represent an endpoint and its abilities with this
shape. The rectangular body represents the endpoint; the bulges on the right side
represent its four abilities.
R
RI
Endpt 1
S
SI
20
| Chapter 3
Implementation—Endpoints (Micro)
Administrators arrange transports to implement endpoints.
Transports
While endpoints are abstract, transports do the real work—transferring message
data between process instances of application programs. Within a program
process, a transport carries messages outbound from the program’s publishers
using an endpoint’s send and send inbox abilities, and inbound to the program’s
subscribers using the endpoint’s receive and receive inbox abilities.
Administrators are responsible for defining appropriate transports to transfer
messages, and for binding those transports to the endpoints of the various
program processes.
In explanatory diagrams, we represent a transport with this shape. The triangular
point indicates that the transport acts outside of an application process (for
example, in a network, or a shared memory segment).
Transport
Connectors
A connector is a configuration within an application instance definition, which
binds a transport to the abilities of an endpoint. Structurally, a connector consists
of a transport and a set of abilities, within the context of an application instance
definition.
The meaning of a connector is that the transport carries messages using that set of
abilities. A connector can bind its transport to one, two, three or all four abilities.
In the graphical configuration interface, connectors appear (unnamed) within
each endpoint on the Application Instance page or on the Application page. To
create a connector, click the Add a Transport icon.
In explanatory diagrams, we represent a connector and its abilities with this
shape. The rectangular body and its label represent the transport; the bulges on
the left side represent the four potential abilities; lines represent the endpoint
abilities that the connector actually binds. The graphical configuration interface
Implementation—Endpoints (Micro) 21
|
for a connector represents the four abilities as check-boxes; each line in this
connector diagram corresponds to a filled check-box in the configuration interface
(see Configuring an Application Instance on page 127 and Endpoint Ability
Check-Boxes on page 129).
R
RI
Tport 1
S
SI
When we depict a connector and its transport as adjacent shapes, we can omit the
transport name from one or the other.
R
Transport
R
RI
S
RI
Tport 1
S
SI
SI
We often depict the connector along with its endpoint, as it would appear in the
context of an application instance.
R
R
RI
RI
S
S
SI
SI
Endpt 1
Tport 1
Using Connectors to Cover Abilities
When a connector binds a transport to an endpoint, in effect it binds the transport
to a subset of the endpoint’s abilities. To be useful, the set of connectors in an
application instance definition must cover the set of abilities that a program uses
for communication. For example, in Figure 1, a program uses an endpoint to
receive one-to-many messages and to send one-to-one messages; an application
instance that binds only the receive ability and the send inbox ability is sufficient
to implement that endpoint for the program (that is, it covers the two abilities that
the program uses). The application instance definition could cover the required
abilities using either one connector, or two. Figure 1 illustrates both of these
possibilities.
22
| Chapter 3
Figure 1 Connectors Cover Endpoint Abilities
R
R
RI
RI
Endpt 1
Tport 1
R
R
RI
RI
Endpt 1
Tport 1
S
S
S
S
SI
SI
SI
SI
R
RI
Tport 2
S
SI
The number of connectors in an application instance definition depends on the
number of abilities that a program requires, and on the transports the
administrator chooses to carry those abilities. In most cases, an application
instance would contain only a few connectors, because it must cover at most four
abilities. Even if an application instance were to use a separate transport to carry
each of the four abilities, it would need at most four connectors to cover them.
Since one transport can carry several abilities, the number of connectors in the
application instance can be less than four.
Implementation—Application (Macro) 23
|
Implementation—Application (Macro)
Administrators view an application program both as an executable program, and
also as a set of process instances of that program, running on one or more host
computers. Arranging process instances on various host computers is one of the
administrator’s responsibilities.
All the process instances of an application program use the same set of
endpoints—developers hard-code that requirement into the program by creating
publishers and subscribers, and by calling their methods.
However, from an administrator’s perspective, it could be necessary or
advantageous for some of the process instances to implement those endpoints
using a different set of transports. For example, process instances on some
computers have access to hardware required to use RDMA transports, while
processes on other computers must use TCP transports. To arrange these
variations, administrators define (within the realm) application definitions and
application instance definitions.
Application Definitions
An application definition is a configuration (within the realm) that represents an
application program, declares its parts (that is, its endpoints and formats), and
configures endpoint implementation for its process instances. Structurally, an
application definition consists of a name, a set of endpoints, a set of application
instance definitions, and a set of preload formats.
Figure 2 on page 24 diagrams the structure of an application definition. To
visualize an application definition as a configuration, see Configuring an
Application Definition on page 123. To create a new application definition, see
Applications Summary on page 122.)
24
| Chapter 3
Figure 2 Application Definition
Name: App 1
Endpoints:
Instance: default
R
RI
Endpt 1
S
SI
R
R
RI
RI
S
S
SI
SI
Endpt 1
Tport 1
Preload Formats:
R
Format 1
RI
Tport 2
S
Format 2
SI
Format 3
The set of endpoints in the application definition must be identical to the set of
endpoints that the program code uses. To ensure agreement, developers and
administrators can use the Endpoint Coordination Form on page 311 as a contract
between program code and realm.
The set of application instance definitions is the central part of an application
definition; see Application Instance Definitions (below).
Administrators also define the set of managed formats that the application
program preloads from the realm server. (For more information, see Defining
Formats on page 12. Formats are orthogonal to endpoint implementation.)
Application Instance Definitions
Application instance definitions configure the implementation of endpoints for
process instances of an application.
Structurally, an application instance definition consists of a name, a set of match
parameters, and a set of connectors to implement each endpoint. To visualize an
application instance definition as a configuration, see Configuring an Application
Instance on page 127.
Implementation—Application (Macro) 25
|
Each application instance definition has two tasks with respect to implementing
endpoints:
•
Statically specify a configuration that satisfies all of the program’s endpoint
and ability requirements.
The set of connectors configures the implementation of endpoints—
accomplishing this task.
•
Dynamically determine a set of process instances that satisfy their
requirements according to that configuration.
The match parameters determine the set of process instances—accomplishing
this task.
Default Instance and Named Instances
Every application definition has a default instance definition. You may also define
an (optional) ordered list of named instance definitions.
A named instance definition can include values for match parameters. The
configuration interface prevents the default instance from including match
parameters.
Matching Instances
A matching algorithm dynamically determines a set of process instances.
The matching algorithm compares attribute values of a process instance against
the match parameter values in the named instance definitions. A process instance
matches a named instance definition when every match parameter you configure in
the named instance definition is identical to the corresponding attribute value in
the process instance. A match parameter without any value (in a named instance
definition) acts like a wildcard; it matches any attribute value in every process
instance.
The order of the named instance definitions within the application definition
determines the order in which the matching algorithm attempts to match them.
The first named instance definition that matches the process instance determines
the endpoint implementation for the process.
If none of the named instances matches the process instance, then the default
instance determines the endpoint implementation for the process. (If you have not
defined any named instances, then the default instance always determines
implementation for all process instances, without matching.)
To configure match parameters, see Host and Identifier on page 128.
26
| Chapter 3
When defining application instances to map from subject names to durables, see
also Matching Instances for Subscriber Name Mapping on page 281.
Result: Instance Connections
In a valid realm definition, all these micro and macro layers (taken together)
statically determine a set of instance connections—which connect the endpoints
(that is, publishers and subscribers within application process instances) with the
transports that implement them. For a visual representation, see Instance
Connections on page 145.
Subscribers and Durables
As noted above, application instance definitions accomplish two tasks with
respect to implementing endpoints.
When an application uses stores and durables, application instances also
accomplish a third task—to determine (for each endpoint) the mapping from
subscriber names to durables; see Configuring Durable Subscribers within an
Application Instance on page 281.
Administrative Requirements 27
|
Administrative Requirements
Administrative requirements for endpoint implementation depend on the
application programs. Each program instantiates a set of endpoints—embodying
them through API objects and method calls, which in turn use a subset of the
endpoints’ abilities. Program developers and administrators must coordinate to
ensure correct endpoint implementation:
•
Developers must specify the endpoints and communication abilities that their
applications use (and inform administrators). In the configuration model,
these are the requirements.
•
Administrators must configure transports and connectors to cover that set of
endpoint requirements. In the configuration model, these are the transport
abilities.
•
Administrators may configure several application instance definitions, each
implementing the endpoints in a different way. In the configuration model,
these are the solutions.
(To facilitate coordination, we recommend that developers complete the Endpoint
Coordination Form, page 311.)
It is an administrative error to leave an ability requirement unsatisfied. When the
application program attempts to use that ability, the API call fails. For example, if
no transport carries an endpoint’s one-to-many receive ability, the subscriber
creation call fails; if no transport carries an endpoint’s one-to-one send ability, the
publisher’s send to inbox call fails.
See Also
Configuration Model, page 16
28
| Chapter 3
Administrative Options
When configuring endpoint implementation, administrative choices affect
transmission characteristics for the application. This section presents some of the
factors to consider when optimizing overall performance.
Transport Type and Abilities
Some transport types are often more appropriate to carry some communication
abilities than others. For example, shared memory transports and multicast
transports are well-suited to carry one-to-many messages.
Transport Type and Host Computer
Some transport types are often more appropriate to application instances that are
co-located on one multi-core host computer, while others are appropriate to
communicate among separate host computers.
For example, shared memory transports are well-suited to carry messages among
co-located application instances. In contrast, TCP, RDMA and multicast
transports are well-suited to carry messages among application instances on
separate host computers.
Segregating Traffic by Priority
When a stream of messages has high priority and low volume, it is often
appropriate to segregate it on a separate transport, away from other streams with
lower priority or high volume.
Multiple Transports
It is possible to configure several transports to carry one endpoint ability. For
example, connectors could specify that a multicast transport and a TCP transport
both carry the send ability. The multicast transport reaches receivers within a
LAN, and the TCP transport reaches remote receivers (when an intervening
hardware router does not forward multicast packets).
When two or more transports carry an endpoint ability, the FTL base library
arranges their communications serially, within one thread, according to the order
that the transports appear in the application instance’s endpoint connectors.
Serial communications apply in two situations:
Administrative Options 29
|
•
Send abilities place outbound message data from a send call on each transport
serially.
•
Receive abilities associated with inline event queues accomplish all six phases
of delivery in a single thread, attending to each transport in a round-robin
arrangement.
(In contrast, receive abilities associated with regular event queues receive
inbound messages from several transports in separate threads. The dispatch
phase merges them into the event queue for dispatch in yet another thread.)
Serial processing can increase latency.
30
| Chapter 3
Sample Configuration 1—tibsend and tibrecv
To clarify the concepts of endpoints and transports, consider the sample
applications tibsend and tibrecv, and the sample realm configuration (see
Sample Programs on page 305). It can be helpful to view the example as a graph
as you read Table 6; see Instance Connections on page 145.
This first example illustrates basic concepts in configuring transports and
endpoint implementation—namely, binding a transport to carry an ability;
configuring connectors; joining endpoints through a common transport; dividing
message streams over separate transports.
Table 6 Sample Configuration—tibsend and tibrecv (Sheet 1 of 2)
tibsend
tibrecv
Program
Description
The sample program tibsend creates a
publisher object, and sends messages
over its one-to-many send ability.
The sample program tibrecv creates a
subscriber object, and receives messages
over its one-to-many receive ability.
Endpoints
The sample realm defines the
application tibsend with one endpoint
(named tibsend-endpoint).
application tibrecv with one endpoint
(named tibrecv-endpoint).
Default Application Instance
First consider the default application instance, and the effect of its configuration.
The sample realm configures the default
application instance of tibrecv,
implementing tibrecv-endpoint with
the transport shm-sendrecv-tport,
which carries the endpoint’s
one-to-many receive ability.
Default
Application
Instance
The sample realm configures the default
application instance of tibsend,
implementing tibsend-endpoint with
the transport shm-sendrecv-tport,
which carries the endpoint’s
one-to-many send ability.
End Result
Notice that the two application instances specify the same transport
(shm-sendrecv-tport) to implement their respective endpoints. The effect is to join
the two endpoints (tibsend-endpoint and tibrecv-endpoint) so that messages
flow between them—from tibsend to tibrecv.
Sample Configuration 1—tibsend and tibrecv 31
|
Table 6 Sample Configuration—tibsend and tibrecv (Sheet 2 of 2)
tibsend
tibrecv
Another Application Instance
Next, consider another application instance, named mcast.
mcast
Application
Instance
End Result
The sample realm configures the mcast
application instance of tibsend, to
match the identifier mcast. For matching
processes, it implements
tibsend-endpoint with the transport
mcast-send-tport, which carries the
endpoint’s one-to-many send ability.
The sample realm configures the mcast
application instance of tibrecv, to
match the identifier mcast. For matching
tibrecv-endpoint with the transport
mcast-recv-tport, which carries the
endpoint’s one-to-many receive ability.
Notice that the two application instances specify a pair of related transports to
implement their respective endpoints. Furthermore, those transports are
complementary—the multicast send group of one is a multicast listen group of the
other. The effect is to join the two endpoints (tibsend-endpoint and
tibrecv-endpoint) so that messages flow between them—from tibsend to
tibrecv.
If several process instances of tibsend and tibrecv were to run (on networked host
computers), their common transport would enable each instance of tibsend to
communicate with each instance of tibrecv.
However, messages do not flow between default application instances and
mcast application instances—they use two different transports, which keep their
message streams separate.
32
| Chapter 3
Sample Configuration 2—tibrequest and tibreply
This second example illustrates additional concepts in configuring transports and
endpoint implementation—namely, binding a transport to carry several abilities;
two-way message traffic; and connection-oriented transports with connecting and
listening ends, linked by a relationship.
Table 7 Sample Configuration—tibrequest and tibreply (Sheet 1 of 2)
Program
Description
Endpoints
tibrequest
tibreply
The sample program tibrequest
creates a publisher object, and sends
messages over its one-to-many send
ability.
The sample program tibreply creates a
subscriber object, and receives request
messages over its one-to-many receive
ability.
tibrequest also creates an inbox
subscriber object, and receives reply
messages over its one-to-one receive
ability.
It responds to each request message by
sending back a reply message over its
one-to-one send ability.
application tibrequest with one
endpoint (named
tibrequest-endpoint).
application tibreply with one endpoint
(named tibreply-endpoint).
Application Instance
Consider the rdma application instance, and the effect of its configuration.
rdma
Application
Instance
The sample realm configures the rdma
application instance of tibrequest, to
match the identifier rdma. For matching
tibrequest-endpoint with the
transport rdma-request-tport, which
carries the endpoint’s one-to-many send
ability, and also its one-to-one receive
ability.
The sample realm configures the rdma
application instance of tibreply, to
match the identifier rdma. For matching
tibreply-endpoint with the transport
rdma-reply-tport, which carries the
endpoint’s one-to-many receive ability,
and also its one-to-one send ability.
Sample Configuration 2—tibrequest and tibreply 33
|
Table 7 Sample Configuration—tibrequest and tibreply (Sheet 2 of 2)
tibrequest
Relationship
tibreply
Notice that the two application instances specify a pair of related transports to
implement their respective endpoints. Furthermore, those transports are
complementary.
The essence of their relationship is that rdma-request-tport and
rdma-reply-tport both specify the same port number. rdma-request-tport is the
connecting end, while rdma-reply-tport is the listening end of the same port.
Once they establish a connection between them, they work together to transmit data
over that link.
End Result
The effect is to join the two endpoints (tibrequest-endpoint and
tibreply-endpoint) so that messages flow between them. The request messages
flow from tibrequest to tibreply, and the reply messages flow in the opposite
direction.
34
| Chapter 3
| 35
Chapter 4
Transports
This chapter presents general information about transports, the available
transport types and their configuration details.
Topics
•
Transport Overview, page 36
•
Unitary and Fragmentary Transport Definitions, page 38
•
Bus Topologies, page 40
•
Pair Connections, page 44
•
Subscriber Interest, page 46
•
Blocking vs Non-Blocking Send, page 47
•
Inline Mode, page 49
•
Receive Spin Limit, page 50
•
UDP Packet Send Limit, page 53
Transport Types
•
Shared Memory Transport, page 55
•
Remote Direct Memory Access Transport (RDMA), page 57
•
Dynamic TCP Transport, page 60
•
Static TCP Transport, page 62
•
Multicast Transport (Mcast), page 64
•
Reliable UDP Transport (RUDP), page 70
•
Process Transport (PROC), page 72
| Chapter 4
Transports
Transport Overview
Transports are the underlying mechanism that facilitate message communication
among endpoint instances in programs. FTL software supports several transport
types. This chapter begins with explanations of transport concepts, and ends with
the details of the transport types (each in its own section).
Transport Roles
Transports have two important runtime tasks:
•
Establish a bus—a shared communication medium.
•
Serve as a communications interface—mediating between endpoint instances
(that is, publishers and subscribers in application processes) and the bus.
Inside a Transport
Figure 3 Transports and Bus
App
E
T
Bus
T
E
E
App
T
Ap p
36
Figure 3 presents a generalized view of transports and their operating roles.
Notice several aspects of this runtime perspective:
•
Endpoint instances are objects within application processes. Application code
uses API calls to create publisher and subscriber objects within application
process instances.
•
Transports are objects that straddle the edge of application processes.
Administrators configure transports in the realm, and FTL base library code
expresses the transport definitions in application processes at runtime. These
Transport Overview 37
|
runtime transports act within the process to fulfill the transport’s two roles
outside the process—they establish a bus, and serve as interfaces between
endpoints and the bus.
•
Transports (and their operating details) remain hidden from application code.
•
The type and details of the bus remain hidden from application code.
•
The bus is conceptually outside the application processes, and transports
mediate between the application program and the bus.
Transport Definitions Must be Unique
It is erroneous to define two (or more) transports with identical transport
configuration values.
For example:
•
Do not configure two transport definitions that access the same shared
memory segment.
•
Do not configure two transport definitions with the same multicast send
group and listen groups.
The scope of this prohibition is even wider than a single realm. If two (or more)
realms exist within the same network, then violating this rule can result in
interference between the realms.
We strongly discourage bending this rule as a technique to bridge between two
realms. Instead, we recommend developing a custom application to translate
messages between realms. Such an application would straddle the realms,
connecting to both realm servers. (The translation application must pay special
attention to the formats of messages as they cross between realms.)
38
| Chapter 4
Transports
Unitary and Fragmentary Transport Definitions
Transport definitions can be either unitary or fragmentary:
•
Unitary—transports in several communicating process instances or process
threads use the same transport definition to establish a bus.
•
Fragmentary—transports in process instances use different transport
definitions, which cooperate to establish a bus.
For example, definitions of shared memory, dynamic TCP and process transports
are inherently unitary. One shared memory segment serves as a bus for endpoints
in many application processes. One transport definition contains all the
information that all the application processes require to establish that bus.
In contrast, static TCP and RDMA transports are inherently fragmentary because
they use connection-oriented protocols to establish a bus. For example,
establishing each static TCP connection requires asymmetric transport definitions
at the listening end and the connecting end. The two transports specify
complementary modes (one listens, the other connects), and the two transports
cooperate (they listen and connect at a common interface and port).
Multicast transport definitions can be either unitary or fragmentary. Multicast
communication does not require any initial connection protocol, so the
determining factor is the use case.
•
In a unitary use case, a set of communicating peers could all use the same
multicast group as their bus. One transport definition suffices; it specifies an
identical multicast group for listen and for send.
•
In the more common fragmentary case, administrators control network data
flow to achieve specific results (such as bandwidth allocation, performance,
data segregation, or asymmetric multicast topologies). A set of shared
multicast groups serve as the bus; applications require different transport
definitions, reflecting their different communication characteristics.
Transport Relationships
A transport relationship is a symmetric relation between two fragmentary
transports.
When defining a transport, T1, an administrator can add a transport relationship,
specifying another transport, T2 (even if T2 is not yet defined). Because the
relationship is symmetric, T2 automatically shares that same relationship with T1.
We say that T1 and T2 are related transports.
Unitary and Fragmentary Transport Definitions 39
|
The FTL base library uses transport relationship information when sending
messages. Administrators must signal that fragmentary transports cooperate by
defining the relationships among them.
However, merely defining a relationship between two transports is not sufficient
for communication. Administrators must also properly configure the related
transports so that they can establish a bus. For example, consider a static TCP
transport, T1, which listens on port 5678, with a relationship to a static TCP
transport, T2, which connects on port 7890. This configuration is erroneous,
because the two related transports cannot establish a TCP connection.
When related transports are properly configured and establish a bus, data flows
between them through the bus. Figure 4 depicts two program processes, each
with one endpoint. A pair of related transports implements the two endpoints.
Curved arrows on the right show the data flow among the abilities of the related
transports. Notice that when process P1 sends a one-to-one message, it flows
through the send inbox ability over transport T1, then into process P2 through the
receive inbox ability of transport T2, and P2 receives it in its inbox (which
instantiates endpoint E2). Transport relationship information plays an important
role in the crossover between the send abilities and the receive abilities.
Figure 4 Related Transports—Data Flow
Process P1
R
R
RI
RI
S
S
SI
SI
E1
T1
Bus
Process P2
R
R
RI
RI
S
S
SI
SI
E2
T2
| Chapter 4
Transports
Bus Topologies
You can configure a set of cooperating transports to establish a bus with a
predetermined topology. This section outlines the configuration techniques for
some example topologies.
Unitary Mesh
The natural topology of a unitary transport definition (such as shared memory,
dynamic TCP, or symmetric multicast) is a mesh (complete graph) over all its
runtime transports. Figure 5 shows that topology with five process instances. Any
process on this bus can send messages to all of its peers, and receive messages
from all of its peers.
Notice that all five processes necessarily use the same transport definition (T) to
join the bus (this is the definition of a unitary transport definition).
Figure 5 Unitary Mesh
A3
A2
E
E
T
T
A4
T
E
E
T
A1
Bus
T
E
A5
40
Assembling Larger Topologies from Pair Connections
The basic building block in connection-oriented transports (such as RDMA, static
TCP or RUDP) is a pair connection, which enables two-way communication
between two runtime transports across a network. You can assemble these basic
parts into larger topologies, such as hub and spoke, or mesh (see below).
Bus Topologies 41
|
Hub and Spoke
Figure 6 shows a hub-and-spoke topology for a server with many clients.
Configure one listen end transport definition for the hub, and one connect end
transport definition for all the spokes. Start the hub application, then start the
spoke applications. (For further information, see Pair Connections on page 44.)
Figure 6 Hub and Spoke Topology
Spokes
Client
E2
T2
T2
Cli
en
t
E2
Hub
T2
E2
Serv
er
E1
T1
Client
Bus
Mesh
Figure 7 on page 42 shows a mesh (that is, a complete graph) with four vertices.
Configure four transport definitions:
•
T1 listens on port P1.
•
T2 listens on port P2, and connects to port P1 (on A1’s host computer).
•
T3 listens on port P3, and connects to ports P1 (on A1’s host computer), and to
port P2 (on A2’s host computer).
•
T4 connects to ports P1 (on A1’s host computer), and to port P2 (on A2’s host
computer), and to port P3 (on A3’s host computer).
| Chapter 4
Transports
Figure 7 Mesh Topology for Connection-Oriented Transport Types
A3
A2
E
E
T3
T2
T1
A4
E
T4
E
Bus
A1
42
Notice that all four processes necessarily use different transport definitions to join
the bus. It cannot be otherwise, because connection-oriented transport definitions
are fragmentary.
Also notice that the four transport definitions (T1–T4) are each tied to specific host
computers. In order to use them, the application process instances (A1–A4) must
run on those host computers, respectively. You can configure this constraint using
application instance definitions that match the Host parameter.
Asymmetric Multicast Topologies
Figure 8 on page 43 shows an asymmetric multicast topology. Three sending
applications (on the left side) can send one-to-many messages to three receiving
applications (on the right side). (You can easily generalize this example to any
number of senders and receivers; the number of senders and receivers need not be
the same.)
Configure these definitions:
•
Transport TS specifies send group G1.
•
Transport TL specifies listen group G1.
•
Connectors in the senders (left) bind TS to carry the send ability.
•
Connectors in the receivers (right) bind TL to carry the receive ability.
Bus Topologies 43
|
Figure 8 Asymmetric Multicast—Bipartite Graph
Senders
Receivers
TS
E
E
TS
TS
R3
E
TL
E
S2
R2
E
TL
S1
E
R1
TL
S3
Bus
Notice that all these processes use only two different transport definitions (TS and
TL) to join the bus, reflecting their opposite roles as either senders or receivers.
44
| Chapter 4
Transports
Pair Connections
When defining connection-oriented transports (such as static TCP, RDMA and
RUDP) the connect end and the listen end must cooperate to establish a
connection.
Listen End and Connect End
The assignment of listen end and connect end is not arbitrary. Instead, it depends
on the type of interaction, or on the bus topology. To simplify transport
configuration, follow the recommendations in Table 8.
In general, a process that must start first is a good candidate for the listen end of
pair connection. This rule helps avoid situations in which programs send
messages before the transport establishes a pair connection bus.
Table 8 Listen End and Connect End
Situation
Listen End
Connect End
Request/Reply Interactions
Replying process
Requesting process
Server and Clients
Server
Clients
Long-Lived Process and
Ephemeral Processes
Long-lived process
Ephemeral processes
Hub and Spoke Topology
Hub
Spokes
Start Order
Administrators must arrange for processes to start in the correct order.
Application semantics drives this precedence—if a requesting process starts
before the replying process, the replying process could miss the first request (or
several requests).
The principles that determine which processes must start first (namely, replying
processes, servers, long-lived processes and hub processes) are similar to the
principles that determine the preference for listen end of a pair connection (see
Table 8).
Pair Connections 45
|
Connect Requests are Specific to IP Addresses
A transport definition for a connect end hard-configures a specific IP address at
the listening end. Consider these consequences:
•
A connect end transport definition can operate on several different host
computers—as long as the listening end port is already open.
•
A listen end transport must run at the location where its connect end
counterparts expect to find it.
•
If you move a listen end process to another host computer, you must
reconfigure its counterpart connect end so it can find the listen end.
•
If you move a connect end process to another host computer, you need not
modify its counterpart listen end.
•
A connect end must direct its connection requests to a listen port on
one specific network interface of the host computer at the listen end. That is,
you must specify either an IP address or a hostname—but * is not valid. The
listen port must be open on that network interface, otherwise the connection
request fails.
•
A listen end transport may open a listen port on all available network
interfaces, or on only one. That is, you may specify * as the host interface, or a
specific IP address or hostname.
46
| Chapter 4
Transports
Subscriber Interest
Whenever possible, publishers send messages only to interested subscribers. That
is, publishers send only those messages that match at least one subscriber content
matcher. This behavior can reduce bandwidth consumption, and can enhance
subscriber performance in some situations.
This behavior extends across a transport bridge when the transports support it
end-to-end.
This behavior is automatic for TCP, RDMA and shared memory transports.
For multicast transports, you must explicitly require subscriber interest, and you
must also configure the transport’s multicast groups to support bi-directional
communication (that is, inbound and outbound) on the transport bus (see
Multicast Groups on page 66). The two directions need not use the same multicast
group. See Require Subscriber Interest on page 65.
Feature Availability
For multicast transports this behavior is available when publishers use the FTL
library from release 4.1 (or later), and subscribers use the FTL library from release
4.0 (or later).
For all other transports this behavior is automatic when the subscriber and
publisher both use the FTL library from release 2.x (or later).
See Also
Chapter 14, Transport Bridge, page 221
Blocking vs Non-Blocking Send 47
|
Blocking vs Non-Blocking Send
Send calls in an application program place outbound messages on a bus (external
to the program process); a transport mediates this I/O operation. Under normal
circumstances, the I/O operation completes quickly, and the send call returns.
If the bus is full (that is, it cannot accept any more messages) then two behaviors
are possible (see the table below). Administrators select one of these two
behaviors, and configure it in the transport definition.
Table 9 Blocking and Non-Blocking Send
Behavior
Description
Blocking Send
When the bus is full, the send call blocks, and does not return until it has
placed all the outbound message data on the bus.
Non-Blocking Send
(Default Behavior)
When the bus is full, the transport buffers outbound messages in a backlog
buffer (in process memory) until the bus can accept them. The send call
returns.
When the bus can accept more messages, the transport automatically moves
them from its backlog buffer to the bus.
If the backlog buffer overflows, the transport discards the oldest messages in
the buffer to make room for new messages. The discarded messages do not
arrive at slow receivers; the base library reports dataloss advisories to slow
receivers.
See Also
Non-Blocking Send on page 133
Shared Memory Transports and One-to-Many Non-Blocking Send
Shared memory transports buffer message data from one-to-many send calls in
the shared memory segment itself (rather than in a backlog buffer in process
memory).
To counteract dataloss in this situation, enlarge the Size of the shared memory
segment in the transport definition (rather increasing the backlog buffer size).
48
| Chapter 4
Transports
Blocking Send and Inline Mode
Programs that use inline event queues must ensure that callbacks return promptly
and do not include operations that might block. If a program with inline event
queues sends messages from within a callback, administrators must ensure that
those outbound transports specify only non-blocking send. In this situation,
blocking send could cause the send call within the callback to block the inline
dispatch thread (even though the programmer expected the send call to return
immediately).
Inline Mode 49
|
Inline Mode
Programs that receive time-sensitive messages can use inline mode to favor low
latency over high throughput. Inline mode reduces inbound message latency by
consolidating transport I/O and message callback processing into one thread.
For a complete description of inline mode, its usage, requirements and
restrictions, see Inline Mode in TIBCO FTL Development.
When specifying inline mode, programmers and administrators must coordinate
to avoid illegal state exceptions. In particular, inline mode for event queues
imposes restrictions on the transports you can use to implement endpoints; see
Transport Restrictions in TIBCO FTL Development, and Application Coordination
Form on page 308.
When specifying inline mode, programmers and administrators must also
coordinate to avoid blocking send operations that could delay callbacks from
returning promptly; see Blocking Send and Inline Mode on page 48.
50
| Chapter 4
Transports
Receive Spin Limit
This section explains the semantics of the transport parameter Receive
and its effect on message latency and CPU resource utilization.
Spin
Limit,
Do not adjust receive spin limit except to achieve specific and well-defined
performance objectives. Do not adjust unless you thoroughly understand all of
the material in this section.
Motivation and Background
If you understand the role of threads in inbound message delivery, you can
eliminate a potential source of latency—by increasing the CPU resources
dedicated to inbound delivery. (For an introduction to message delivery, see
Delivering Inbound Messages in TIBCO FTL Development.)
Polling for Data
FTL code polls for available data during two phases of inbound message delivery:
•
In the receive phase, to receive data from a transport’s data source
•
In the dispatch phase, to take messages from an event queue
The paradigm is identical in both polling phases:
1. Determine the time limit for polling—that is, the receive spin limit.
2. Poll for available data.
— If available, get the data and return it.
— If not, continue polling until the time limit elapses.
3. When the time limit elapses, block until data becomes available. Blocking
relinquishes the CPU resource to do other work.
Threads and Latency
Polling code operates within a thread.
•
If the thread is already executing on a CPU core, and polling for data, then
when data becomes available, the thread immediately gets the data—without
adding latency.
•
However, if the thread has blocked, the context switching time until it
resumes execution adds to message latency. If it is crucial that your
Receive Spin Limit 51
|
application minimize latency, then consider avoiding this situation by
adjusting receive spin limit.
Tuning Receive Spin Limit
The default value for receive spin limit is 0.01 seconds—a value that yields good
performance in many situations.
When necessary, administrators can adjust receive spin limit as a parameter of
individual transport definitions; see Receive Spin Limit on page 133.
Tuning for Minimal Latency
Blocking frees CPU resources for other threads. However, if minimal latency is
crucial and CPU resources are plentiful, then you can avoid blocking by adjusting
receive spin limit.
If unacceptable latency spikes occur during conditions of sparse message traffic,
one possible cause could be that messages arrive shortly after the receive spin
limit has elapsed, so the polling thread has recently blocked. In this situation,
consider increasing the receive spin limit to a value that is greater than the
maximum expected time between messages. Select a value that is large enough to
prevent threads from blocking between consecutive messages. Test the results
empirically.
Coordinate with developers to understand the thread behavior of application
programs. When the application program creates many dispatch threads, use
caution when increasing receive spin limits. Avoid starving threads by
monopolizing CPU resources.
Tuning to Optimize CPU Resources
If CPU resources are scarce or expensive, then consider decreasing the receive
spin limit so threads that are waiting for data relinquish their CPU resources to do
other work.
Zero is an acceptable value. FTL polls for available data only once. If data is not
available, then FTL blocks immediately.
From Transports to Dispatch
Receive spin limit is a parameter of transports, but its value governs the behavior
of two delivery phases (as described above).
52
| Chapter 4
Transports
The receive phase operates at the transport level, and takes its receive spin limit
directly from the transport definition.
The dispatch phase operates at the event queue level, and inherits its receive spin
limit as the maximum value over all the transports that feed messages into the
event queue (see Figure 9 on page 52).
Figure 9 Receive Spin Limit—Example with Several Transports
T1
T2
T3
Administrator
Perspective
E1
E2
Programmer
Perspective
S1
S2
Q1
Inline Mode
Regular operation separates the receive and dispatch phases into distinct threads.
In contrast, inline mode merges the phases into a single thread—the thread in
which the program calls the dispatch method. Accordingly, for inline mode the
governing spin limit in both polling phases is the maximum value over all the
relevant transports (as mentioned above regarding the dispatch phase).
UDP Packet Send Limit 53
|
UDP Packet Send Limit
With UDP-based transports such as multicast, fast sending programs can
overwhelm slower receiving programs, which could result in
retransmission-related latency, extra resource consumption (CPU cycles and
network bandwidth), retransmission storms, or data loss. To prevent these
scenarios, FTL can limit the rate at which sending programs transmit UDP
packets to the network.
Administrators can empirically tune the flow of data packets from sending
programs by adjusting the Packet Send Limit—a required property of
UDP-based transports.
Limiting the packet send rate also limits the data send rate (bytes per second),
because the data send rate varies with the packet rate and the data sizes of the
packets. However, even if the data send rate is low, a high packet send rate can
still overwhelm a receiver. Hardware limits on the number of NIC I/O interrupts
translate into limits on the receiver’s inbound message rate. When an inbound
packet arrives, the cost of the NIC interrupt is independent of the size of the data
in the packet.
General Guidelines
•
Tune the packet send limit parameter on the senders’ transports (this
parameter has no effect at the receiving end).
•
When an application sends batched messages (that is, several messages per
send call), it is probably already using UDP bandwidth efficiently. We
recommend setting the packet send limit to zero. However, if slow receivers
report dataloss, then consider tuning the packet send limit (as explained
below).
•
When an application rapidly sends small messages singly (that is, one
message per send call), then adjust the packet send limit to increase
54
| Chapter 4
Transports
throughput efficiency. Use these guidelines as you empirically tune this
parameter:
— The general goal is to determine the highest value that does not overwhelm
any receiving hardware.
— To begin, try a value within the range 50,000 to 150,000 packets per second
(depending on capacity of the receiving CPUs to handle NIC interrupts.)
— To reduce average latency, try raising the value.
— If the number of packets overwhelms any receiver, try a lower value—
which raises average throughput by utilizing MTU capacity more
efficiently.
See Also
Multicast: Packet Send Limit, page 66
Shared Memory Transport 55
|
Shared Memory Transport
Endpoints in programs that run on the same host computer can communicate
using a shared memory transport. Shared memory transports communicate at
high speeds, and exhibit very low latency.
Shared memory transports are an excellent strategy for fast communication
among processes on multi-core hardware.
Shared memory transport definitions are inherently unitary.
Topology
The natural topology of a shared memory bus is the mesh (complete graph) of all
its runtime transports. All runtime transports can use the bus for both sending
and receiving operations. When appropriate, you can configure connectors to
artificially limit the abilities that an endpoint may use.
Non-Blocking Send
See Shared Memory Transports and One-to-Many Non-Blocking Send on page 47.
Configuration Parameters
Table 10 describes the parameters specific to shared memory transports in the
configuration interface. For parameters that are common to several transport
types, see Configuring a Transport Definition on page 131.
Table 10 Transport Configuration Parameters: Shared Memory (Sheet 1 of 2)
Parameter
Description
Segment Name
Required.
Name of the shared memory segment.
We recommend only ASCII alphanumeric characters in the segment name.
The maximum length of the segment name depends on the operating system:
•
Mac OS X: 16 characters
•
UNIX: PATH_MAX
•
Windows: MAX_PATH
56
| Chapter 4
Transports
Table 10 Transport Configuration Parameters: Shared Memory (Sheet 2 of 2)
Parameter
Description
Size
Required.
Size of the shared memory segment. (See also Size Units, page 109.)
Directory Name
Optional.
Each FTL shared memory transport uses a scratch directory to store
information about the runtime transports that use its shared memory
segments.
When present, this directory path specifies the scratch directory. (If the
directory you specify doesn’t exist in the file system, FTL attempts to create it.)
When absent, the default scratch directory is /tmp (or its equivalent on
non-UNIX platforms).
Global Scope
Windows only (on other platforms, the base library ignores this parameter).
On Windows platforms, shared memory segments can either be local to a
specific username (that is, a login name) or global (available to all usernames).
To use a global segment, enable this feature. If the process instances using the
transport run with different usernames, then you must use a global segment.
To use a local segment (specific to the user running the application process),
disable this feature. You may use a local segment only if the process instances
using the transport all run with the same username.
For further information, see
msdn.microsoft.com/en-us/library/aa366537%28VS.85%29.aspx.
Remote Direct Memory Access Transport (RDMA) 57
|
Remote Direct Memory Access Transport (RDMA)
On computers that support remote direct memory access (RDMA), network
adapters can move data directly from memory in one computer to memory in
another computer (across a network). This strategy can reduce or eliminate
several sources of latency resulting from overhead—including network protocol
overhead, operating system overhead, context switching overhead.
On each host computer, FTL allocates buffers for each connection on an RDMA
transport.
RDMA is a connection-oriented protocol. Its transport definitions are inherently
fragmentary; you must define at least two complementary transport definitions to
establish a bus. For more information, see Pair Connections on page 44.
Although an individual RDMA connection links exactly two host computers, you
can combine several connections into a bus with a more complex topology; see
Assembling Larger Topologies from Pair Connections on page 40.
Table 11 describes the parameters specific to RDMA transports in the
Table 11 Transport Configuration Parameters: RDMA (Sheet 1 of 2)
Parameter
Description
Pair Connection Settings
You must specify at least one triplet (host, port and initialization mode).
Host
Required.
For the host, specify an RDMA interface either as a host name or as an IP
address.
Asterisk (*) is a special value, which designates all RDMA interfaces on
the host computer (analogous to INADDR_ANY, but limited to RDMA
interfaces). This special value is available only with Listen mode (that is,
RDMA transports can listen for connections on all network interfaces, but
they must connect to a specific interface).
Port
Required.
Specify a port number.
58
| Chapter 4
Transports
Table 11 Transport Configuration Parameters: RDMA (Sheet 2 of 2)
Parameter
Description
Mode
Required.
You must select either Connect or Listen as the initialization protocol
mode:
•
Connect—the transport initiates RDMA communication by sending a
connection request to host:port.
•
Listen—the
transport listens for RDMA connection requests at
host:port.
For more information, see Listen End and Connect End on page 44.
Other RDMA Properties
Source Address
Optional. Specify an IP address.
When the host computer initializing an RDMA connection request has
more than one local interface, the transport attempts outward connection
requests over this interface.
When absent, the transport attempts outward connection requests over
all the available interfaces (in an indeterminate order).
This parameter does not affect a transport’s ability to listen for inbound
connection requests.
Transport
Relationships
You must create a relationship with all other transports that cooperate to
establish a bus.
RDMA Hardware
FTL RDMA transports require hardware that is compliant with implementation
standards in Table 12.
Table 12 RDMA Hardware (Sheet 1 of 2)
Platform
RDMA Hardware
Linux
InfiniBand HCA; RoCE
Remote Direct Memory Access Transport (RDMA) 59
|
Table 12 RDMA Hardware (Sheet 2 of 2)
Platform
RDMA Hardware
Windows Server 2008 R2
InfiniBand HCA
RDMA Implementation Libraries
In addition to RDMA hardware, the FTL RDMA transports require the verbs and
RDMACM libraries from OFED.
Table 13 RDMA Driver Libraries
Platform
Driver Support
Linux
ofed-1.5.1
Windows Server 2008 R2
ofed-3.1
(or later)
(or later)
Locked Memory Buffers
The FTL library reserves buffers for RDMA transports. These buffers are locked—
that is, the operating system cannot swap them out to virtual memory.
For each RDMA connection FTL attempts to allocate 4 megabytes of locked
memory—that is, 128 buffers of length 32 kilobytes each (64 buffers for sending
messages, and another 64 buffers for receiving messages).
On Linux platforms, set the user-level locked memory with the ulimit command;
for example:
ulimit -l unlimited
On Linux platforms with the PAM limits module, set the system-level locked
memory values in the file /etc/security/limits.conf; for example:
* soft memlock 8192
* hard memlock unlimited
Supply values either in kilobytes, or as the string unlimited.
60
| Chapter 4
Transports
Dynamic TCP Transport
A TCP transport enables communication over a set of dedicated connections. To
configure a full mesh topology using TCP links, we recommend dynamic TCP
transports.
In contrast, for other topologies (such as hub-and-spoke), use static TCP (see
Static TCP Transport on page 62).
Dynamic TCP uses transport definitions that are inherently unitary. Nonetheless,
it establishes a bus composed of individual TCP pair connections. However, all
the details of those pair connections—listening end, connecting end, host and
port—are transparent to the administrator. The application and the realm server
arrange those details automatically and dynamically.
The resulting mesh is limited to applications that connect to a single realm server
process. That is, applications that connect to a satellite realm server cannot
participate in a dynamic TCP bus with applications that connect to the primary
realm server. However, such applications can still communicate through a
transport bridge connecting dynamic TCP meshes at different locations (see
Bridges among Dynamic TCP Meshes on page 236).
Table 15 describes the parameters specific to static TCP transports in the
Table 14 Transport Configuration Parameters: Dynamic TCP (Sheet 1 of 2)
Parameter
Description
Advanced Settings
Optional.
Subnet Mask
Limit the hardware interfaces that this TCP transport can use.
When network administrators allocate subnets for specific purposes, use
this parameter to comply.
Specify a CIDR mask; for example, 192.168.2.0/24.
Dynamic TCP Transport 61
|
Table 14 Transport Configuration Parameters: Dynamic TCP (Sheet 2 of 2)
Parameter
Description
Port
Designate a specific port to establish a TCP bus.
When zero or absent, dynamic TCP transports use ephemeral listen ports
to establish a bus. A firewall can thwart this mechanism. To circumvent
the obstacle, designate a specific port for this purpose, and arrange for
the firewall to open that port.
When present, all applications that use the transport use this port to
establish a bus. Notice that using this feature implies a restriction—only
one application per host computer can use this dynamic TCP transport
(as only one application can bind the listen port).
62
| Chapter 4
Transports
Static TCP Transport
A TCP transport enables communication over a set of dedicated connections. Use
static TCP for other topologies (such as hub-and-spoke.
In contrast, to configure a full mesh topology using TCP links, we recommend
dynamic TCP transports (see Dynamic TCP Transport on page 60).
Static TCP is a connection-oriented protocol. Its transport definitions are
inherently fragmentary; you must define at least two complementary transport
definitions to establish a bus. For more information, see Pair Connections on
page 44.
Although an individual static TCP connection links exactly two host computers,
you can combine several connections into a bus with a more complex topology;
see Assembling Larger Topologies from Pair Connections on page 40.
Table 15 describes the parameters specific to static TCP transports in the
Table 15 Transport Configuration Parameters: Static TCP (Sheet 1 of 2)
Parameter
Description
Host
Required.
For the host, specify a static TCP interface either as a host name or as an
IP address.
Asterisk (*) is a special value, which designates all TCP interfaces on the
host computer (that is, INADDR_ANY). This special value is available only
with Listen mode (that is, TCP transports can listen for connections on
all network interfaces, but they must connect to a specific interface).
Port
Required.
Static TCP Transport 63
|
Table 15 Transport Configuration Parameters: Static TCP (Sheet 2 of 2)
Parameter
Description
Mode
Required.
You must select either Connect or Listen as the initialization protocol
mode:
•
Connect—the
•
Listen—the
transport initiates TCP communication by sending a
transport listens for TCP connection requests at host:port.
Transport
Relationships
establish a bus.
64
| Chapter 4
Transports
Multicast Transport (Mcast)
A multicast transport enables reliable multicast communication among endpoints
on many host computers. Multicast transports are efficient for high fan-out
communication across a LAN. Multicast transports use a negative
acknowledgement protocol for reliable message transfer.
Multicast transports excel at one-to-many communications.
Starting with release 4.0, multicast transports can also support one-to-one
communications. For example, servers can send one-to-one replies to individual
clients (requestors). For configuration details, see Configuring Multicast Inbox
Communication on page 68.
Starting with release 4.1, multicast transports can filter messages by subscriber
interest. For backward compatibility issues, see TIBCO FTL Release Notes.
Multicast Group as Shared Communication Medium
Multicast transport definitions can be either unitary or fragmentary. They do not
require any initial connection protocol, so the determining factor is the use case.
•
In a unitary use case, a set of communicating peers could all use the same
transport. For example, all endpoints send on the same multicast group, and
all endpoints listen to the same group (or groups).
•
In the more common fragmentary case, administrators control network data
flow to achieve specific results (such as bandwidth allocation, performance,
data segregation, or asymmetric multicast topologies). Sending peers and
listening peers use related transports with the same port, but different send
and listen groups.
Multicast Transport (Mcast) 65
|
Table 16 describes the parameters specific to multicast transports in the
Table 16 Transport Configuration Parameters: Multicast (Sheet 1 of 4)
Component or
Property
Description
Host
Optional.
Specify a network interface. You may supply an IP address in dot-decimal
notation. The transport resolves the value of the host parameter when the
application establishes a bus.
If you supply an IP address, the transport first treats the IP address as a host
address, comparing it against the interface addresses of the host computer; it
uses the first matching interface. If it does not find a direct match, the
transport next treats the IP address as a network address (subnet), and
compares the IP address against the network addresses of the interfaces of
the host computer; it uses the first interface address whose network address
matches the IP address.
Asterisk (*) is a special value, which designates all network interfaces on the
host computer (that is, INADDR_ANY).
When absent, the transport uses the default interface address. First it calls
to get the hostname string. Then it calls gethostbyname with
that hostname to get the IP address of the default network interface.
gethostname
Port
Required.
Specify a multicast port.
Require Subscriber
Interest
When enabled, the multicast transport carries only those messages that
match subscriber interest—filtering outbound messages at sending
endpoints; see Subscriber Interest on page 46.
However, enabling this parameter is not sufficient. You must also configure
the transport’s multicast groups to support bi-directional communication (that
is, inbound and outbound) on the transport bus (see Multicast Groups on
page 66). The two directions need not use the same multicast group.
When disabled, the multicast transport carries all messages—without
filtering. This value is the default, for backward compatibility.
66
| Chapter 4
Transports
Component or
Property
Description
Multicast Groups
Listen Groups
The transport joins all the listen groups that you specify. You may configure
between zero and 64 listen groups.
A listen group enables inbound communication.
When absent, the transport does not support these two types of
communication.
Send Group
When present, the transport sends on this multicast group. You may supply
at most one send group.
A send group enables outbound communication.
When absent, the transport does not support these two types of
communication.
Send Limit
Packet Send Limit
Required. Use this upper limit to prevent fast senders from overwhelming
slower receivers.
This value limits the maximum number of UDP packets per second that a
program can send over the multicast transport. When a sending program
exceeds this maximum, the FTL library buffers the excess packets in order to
keep the transport’s outbound packet rate at or below this limit.
Zero is a special value, indicating no upper limit on sending programs.
For a detailed explanation, see UDP Packet Send Limit on page 53.
|
Component or
Property
Description
Reliability
Reliability Time
Required.
FTL retains multicast data during this time window (a floating point value,
in seconds).
Transports in sending applications retain recent multicast data in order to
redeliver data to receiving applications upon request.
The reliability time of the sending transport determines the effective
reliability window of all applications receiving data from it. A receiving
transport does not request data beyond the reliability window of the sending
transport (even if the receiver configures a longer reliability window).
For this value, FTL supports time granularity of 0.001 (1 millisecond), and a
maximum value of 120.0 seconds (2 minutes). The FTL base library (within
application programs) throws an exception when it detects a non-zero value
less than 1 millisecond or greater than 120 seconds.
Zero is a special value; sending transports do not store data for
retransmission; receiving applications never request retransmission.
Reliability Memory
When present, FTL retains multicast data up to this maximum (in bytes). (See
also Size Units, page 109.)
When absent, the default is zero (a special value indicating no reliability limit
by size).
Loopback
Enable Loopback
On Send
When enabled, the transport includes the loopback interface in its bus, so
co-located application processes can communicate over the multicast bus.
(Otherwise the multicast bus carries messages only over the network.)
To properly configure loopback behavior, enable this parameter for all the
transports of the bus that use loopback—that is, on the sending transports
and the receiving transports. (The internal details of loopback semantics vary
by operating system. We recommend configuring for consistent behavior on
every platform, rather than coupling the transport definition to a specific
operating system.)
68
| Chapter 4
Transports
Component or
Property
Description
Sizing
UDP Send Buffer
Size
When present, FTL requests a buffer of this size (in bytes) for outbound
multicast data. (Operating system constraints can limit this request.) The
value must be a non-negative integer. (See also Size Units, page 109.)
When absent or zero, FTL requests the default buffer size, 16MB.
In most situations we recommend the default buffer size. In high-volume
situations, larger buffers could yield higher throughput (depending on other
factors).
UDP Receive Buffer
Size
When present, FTL requests a buffer of this size (in bytes) for inbound
multicast data. (Operating system constraints can limit this request.) The
value must be a non-negative integer. (See also Size Units, page 109.)
factors).
Retransmission Control
Retransmission
Control
When present, the transport suppresses retransmission requests from
receivers that miss packets in excess of this loss percentage.
When absent, the transport always requests retransmission (within the
reliability window).
For details, see Multicast Retransmission Control on page 69.
Transport
Relationships
For a fragmentary transport definition, you must create a relationship with
all other transports that share a multicast group in common with this
transport.
For a unitary transport definition, relationships are not needed (you must
omit them).
Configuring Multicast Inbox Communication
Multicast transports can carry one-to-one communication:
|
1. Configure the transport’s multicast groups to support bi-directional
communication (that is, inbound and outbound) on the transport bus (see
Multicast Groups on page 66). The two directions need not use the same
multicast group.
2. Enable the send inbox and receive inbox abilities for endpoints that use the
transport.
Multicast Retransmission Control
The high volume of retransmission requests from chronically slow or lossy
receivers can overwhelm publishing applications, and even overwhelm the entire
network. Receiver loss can result from faulty network hardware, oversubscribed
applications, or underpowered host computers.
Retransmission control is a tool to detect lossy receivers and suppress their
retransmission requests. Administrators can set a receiver loss threshold; if the
percentage of lost packets between any pair of multicast subscriber and publisher
exceeds this limit, then the transport suppresses all retransmission requests from
that subscriber to that publisher.
To configure this threshold, see Retransmission Control on page 68.
70
| Chapter 4
Transports
Reliable UDP Transport (RUDP)
A reliable UDP (RUDP) transport enables reliable communication over a set of
dedicated connections. Endpoints on an RUDP bus exchange UDP datagrams.
RUDP transports use a positive acknowledgement protocol for reliable message
transfer.
Consider using RUDP transports for network client-server communications that
are not sensitive to latency, in situations of high fan-out (or fan-in) and low data
volume. (TCP yields faster data transfer. However, RUDP features more efficient
fan-out; RUDP consumes only one socket, which accepts many connections.)
RUDP is a connection-oriented protocol. Its transport definitions are inherently
fragmentary; you must define at least two complementary transport definitions to
establish a bus. For more information, see Pair Connections on page 44.
Although an individual RUDP connection links exactly two host computers, you
can combine several connections into a bus with a more complex topology; see
Assembling Larger Topologies from Pair Connections on page 40.
Table 17 describes the parameters specific to RUDP transports in the
Table 17 Transport Configuration Parameters: RUDP (Sheet 1 of 2)
Component or
Property
Description
Host
Required.
For the host, specify an RUDP interface either as a host name or as an IP
address.
Asterisk (*) is a special value, which designates all RUDP interfaces on the
host computer (that is, INADDR_ANY). This special value is available only with
Listen mode (that is, RUDP transports can listen for connections on all
network interfaces, but they must connect to a specific interface).
Reliable UDP Transport (RUDP) 71
|
Table 17 Transport Configuration Parameters: RUDP (Sheet 2 of 2)
Component or
Property
Description
Port
Required.
Mode
Required.
You must select either Connect or Listen as the initialization protocol mode:
•
Connect—the
•
Listen—the
transport initiates RUDP communication by sending a
transport listens for RUDP connection requests at host:port.
Sizing
UDP Send Buffer
Size
When present, FTL requests a buffer of this size (in bytes) for outbound
RUDP data. (Operating system constraints can limit this request.) The value
must be a non-negative integer. (See also Size Units, page 109.)
factors).
UDP Receive Buffer
Size
When present, FTL requests a buffer of this size (in bytes) for inbound RUDP
data. (Operating system constraints can limit this request.) The value must be
a non-negative integer. (See also Size Units, page 109.)
factors).
Transport
Relationships
establish a bus.
72
| Chapter 4
Transports
Process Transport (PROC)
Endpoints within a single program process can communicate using a process
(PROC) transport. Process transports communicate at high speeds, and exhibit
very low latency.
Process transports are an excellent strategy for fast communication among
threads within a process.
Process transport definitions are inherently unitary.
Process transports cannot participate in transport bridges.
Administrators arrange process transports only when program developers
request it.
For best performance, avoid binding an endpoint to both a process transport and
a slower transport (as the slower transport limits the performance of the process
transport).
Table 18 describes the parameters specific to process transports in the
Table 18 Transport Configuration Parameters: PROC
Component or
Property
Description
Buffer Size
Required.
A process transport passes messages between threads through a buffer in
process memory. This parameter determines the maximum number of
messages that the buffer can hold.
When the buffer is full a non-blocking process transport discards new
messages from the sending endpoint (instead of placing them in the buffer).
Blocking process transports block until the buffer can accept the new
message.
| 73
Chapter 5
Realm Server
This chapter presents the realm server utilities, their command line options and
configuration parameters.
Topics
•
Realm Server Overview, page 74
•
Affiliated Realm Servers, page 75
•
Realm Server Authentication and Authorization, page 82
•
Option and Property Names, page 84
•
Using the tibrealmserver Executable, page 85
•
Using the tibrealmadmin Utility, page 94
74
| Chapter 5
Realm Server
Realm Server Overview
The realm server contains the complete realm definition. FTL application
programs request the realm definition from the server, which responds with a
version of the realm that is tailored for a specific application. The application
process stores this tailored realm definition in a realm object.
Administrators configure, run and maintain the realm server, which includes
configuring the realm definition in the server.
The realm server can run either as a singleton process, or as a family of affiliated
server processes—which can include a primary server, satellite servers, and
backup servers (for fault tolerance). For more information, see Affiliated Realm
Servers on page 75.
These sections describe the executable files related to the realm server:
•
Option and Property Names, page 84
•
Using the tibrealmserver Executable, page 85
•
Using the tibrealmadmin Utility, page 94
Affiliated Realm Servers 75
|
Affiliated Realm Servers
You can configure a family of affiliated realm server processes that coordinate
within a single realm, distributing the task of serving the realm definition to their
clients.
Server Roles and Relationships
Affiliated realm server processes are connected by relationships, which in turn
place each affiliated server in a specific role. Administrators configure the
relationships among affiliated servers using command line parameters or
configuration file properties (see Affiliated Servers on page 87).
Figure 10 Affiliated Realm Servers: Roles and Relationships
backup to
Primary
Backup
backup for
satellite of
satellite of
satellite of
backup to
Satellite
(New York)
Backup
backup for
backup to
Satellite
(New Jersey)
Backup
backup for
Satellite
(Connecticut)
backup to
Backup
backup for
Primary
The primary server is the central hub within a family of affiliated servers.
76
| Chapter 5
Realm Server
•
Within a family of affiliated server processes, exactly one process can play the
role of primary.
•
Administrators can update the primary’s realm definition (using the graphical
configuration interface or a realm server Python script). The primary can
deploy updates to its clients, and to other affiliated servers.
•
Client application processes can connect to the primary. Satellite server
processes can connect to the primary.
Satellite
A satellite server provides local service to clients that are geographically distant
from the primary, or clients that are insulated from the primary (to fulfill
enterprise requirements). Administrators can arrange satellite servers in order to
reduce remote connection costs, or to distribute client load. Consider a server S,
which is a satellite of the primary P:
•
Several servers can be satellites of the primary. A server cannot be a satellite of
another satellite server, nor of a backup server.
•
Satellite server S initiates a TCP connection to primary P (and not the reverse).
•
Satellite S receives the realm definition from primary P. When an
administrator deploys an updated realm definition to P, P pushes the
deployment to S. (Administrators cannot deploy updates directly to a satellite
server.)
•
Each client connects either to P or S (or some other satellite) as its realm server.
Primary P and all its satellites serve sets of clients that are disjoint from one
another.
•
Satellite S is loosely coupled to the primary P. If one of them became
inoperative, or the connection between them broke, P would not take any
restorative action. S would attempt to reconnect to P, yet would continue to
serve its clients in the interim. P can deploy a new realm definition while S is
disconnected (but see Disconnected Satellite on page 78).
Backup
A backup server provides fault-tolerant service to clients of a regular server (which
can be either the primary or a satellite). For example, consider a regular server R
(either the primary or a satellite), which has a backup to server B:
•
The primary server can back up to at most one backup server. Each satellite
can back up to at most one backup server. A backup server cannot back up to
another backup server.
•
Regular server R initiates a TCP connection to backup B (and not the reverse).
|
See Also
•
Regular server R pushes its realm definition to backup B. When R deploys an
updated realm definition, it pushes the update to B. (Administrators cannot
deploy updates directly to a backup server.)
•
Each client that connects to R as its realm server also designates B as its
backup server for fault tolerance. R and B serve the same set of potential
clients.
•
Backup server B does not accept client connection requests unless regular
server R becomes inoperative. In this failover situation, clients of R
automatically connect to B instead. When R is fully operative again, clients
disconnect from B and reconnect to R.
•
Regular server R is tightly coupled to its backup B. If one of them became
inoperative, or the connection between them broke, they would warn the
administrator and take action. That is, R would attempt to restore the
connection to B; B would begin failover operation.
•
If R and B are disconnected when R receives a realm update, R cannot accept
the update. The administrator must first ensure that R and B have
reconnected, then try the update again.
Primary Out of Sync with Backup, page 79
Summary of Roles
Table 19 Affiliated Realm Servers—Role Summary (Sheet 1 of 2)
Primary
Satellite
Backup
Realm Definition
Can receive updates
from administrators.
Can receive updates
only from the primary.
Can receive updates
only from its regular
server.
Numerical Limits
Only one primary per
realm.
No limit.
One backup per
regular server.
Initiating TCP
Connections
Connects to its
backup.
Connects to the
primary, and to its
backup.
Does not initiate
connections
78
| Chapter 5
Realm Server
Table 19 Affiliated Realm Servers—Role Summary (Sheet 2 of 2)
Accepting TCP
Connections
Primary
Satellite
Backup
Accepts connections
from satellites.
Accepts connections
from clients.
Accepts connections
from its regular server.
Accepts connections
from clients, but only
when its regular
server fails.
Accepts connections
from clients.
Monitoring Interface
Administrators can
monitor and manage
clients and satellites.
Administrators can
monitor and manage
clients.
Administrators can
monitor and manage
clients.
Configuration
Interface
Administrators can
edit the realm
definition and deploy
updates to clients,
satellite servers and
backup servers.
Administrators can
view the realm
definition (read-only).
Administrators can
view the realm
definition (read-only).
Modifying the Realm Definition
Administrators can modify the realm definition using the browser configuration
interface.
•
Only the primary server can accept realm modifications and updates directly
from administrators.
•
A satellite server can accept updates only from the primary server.
•
A backup server can accept updates only from its regular server (that is, the
server for which it plays the role of backup).
Disconnected Satellite
Before attempting to deploy an updated realm definition, we strongly recommend
that administrators check the health of all affiliated servers and correct any
network issues.
A primary server with a backup (and a satellite server with a backup) cannot
accept updates unless it is connected to its backup server.
|
Although a primary server can accept an update even while disconnected from a
satellite, we do not recommend this practice, as it can cause administrative
complexities.
Consider a situation in which a satellite S is inoperative or disconnected from the
primary P—nonetheless, an administrator deploys an updated realm definition to
a family of affiliated servers. The deployment can proceed (unless some other
condition prevents it, such as a No answer from a client).
Meanwhile, if satellite S is still operating, it continues to service client requests
with information from the outdated realm definition. If S is inoperative, clients
migrate to its backup server, which also serves information from the outdated
realm definition.
When S reconnects to P, P deploys the updated realm definition to S. Because the
update is already deployed at other affiliated servers, P does not first test the
update against S and its clients. Instead, P deploys the update to S, and S
immediately deploys it to its clients and its backup server—even though the
update might cause difficulties for some clients of S.
If you must deploy an updated realm definition in such circumstances, then as S
reconnects and deploys the update, it is prudent to carefully monitor its clients.
Primary Out of Sync with Backup
In rare situations, it is possible that the primary server can have a newer
deployment than its backup server. This situation automatically resolves itself
when the primary and backup servers reconnect.
In extremely rare situations, it is possible that a backup server B can have a newer
deployment than its primary server P.
It is important to resolve this anomalous situation.
To recover, the administrator must do these steps:
1. Stop primary server P; see --shutdown on page 95.
2. Back up the database at B (the result is a zip file); see --backup_database on
page 95.
80
| Chapter 5
Realm Server
3. Replace the database files on P with the contents of that zip file:
a. Copy the zip file to the primary’s host computer.
b. Navigate to the data folder for P, see --data on page 85.
c. Extract the contents of the zip file into the data folder, overwriting existing
files. (This operation overwrites some of the existing database files, but not
all of them.)
4. Restart P.
Configuring Fault Tolerance
The primary server and each satellite server can each designate at most one
backup server.
Task A Starting the Backup Server
1. Supply the --backupfor parameter, to start as a backup server.
2. If authentication is required, supply the --server.user and
--server.password parameters, with credentials that the backup server can
use to authenticate itself to the regular server.
Ensure that this username is in the authorization group ftl-backup.
Task B Starting the Regular Server
The regular server can be either the primary server or a satellite server.
3. Supply the --backupto parameter, indicating the location of the backup server
(see Connect Port).
--server.password parameters, with credentials that the regular server can
use to authenticate itself to the affiliated servers.
Ensure that this username is in the appropriate authorization group—either
ftl-primary or ftl-satellite.
If satellites and backups require different authentication credentials, then also
supply the --server.authtobackup.user and --server.authtobackup.password
parameters (which the regular server uses to authenticate itself to its backup
server).
|
Task C Configuring Clients
5. In the realm connect call, programmers supply the locations of two realm
servers:
•
Supply the location of the regular server as the realm server URL argument
(see Connect Port).
•
Supply the location of the backup server as the value of the secondary server
property (see Connect Port).
Configuring Satellites
The primary server can designate satellite servers.
Task D Starting the Primary Server
--server.password parameters, with credentials that the primary server can
use to authenticate itself to the satellite servers.
Ensure that this username is in the authorization group ftl-primary.
Task E Starting a Satellite Server
2. Supply the --satelliteof parameter, indicating the location of the primary
server (see Connect Port).
--server.password parameters, with credentials that the satellite server can
use to authenticate itself to the primary server.
Ensure that this username is in the authorization group ftl-satellite.
82
| Chapter 5
Realm Server
Realm Server Authentication and Authorization
The realm server can use JAAS to authenticate client programs, administrative
tools, and affiliated servers.
To specify a JAAS configuration file, see --jaas on page 91.
You must configure the JAAS file to meet these requirements:
Table 20 Configuring JAAS
Authorization Group
Usage
tibrealmserver
The name of the JAAS realm must be tibrealmserver.
ftl
Realm servers require FTL client programs to authenticate with
usernames in the authorization group ftl.
ftl-admin
Authenticated users in the authorization group ftl-admin can view
realm definition and monitoring pages. They can also modify the realm
definition and execute administrative operations.
ftl-guest
Authenticated users in the authorization group ftl-guest can view
realm definition and monitoring pages. However, they cannot modify the
realm definition nor execute administrative operations.
ftl-primary
Affiliated realm servers require the primary server to authenticate with a
username in the authorization group ftl-primary.
ftl-satellite
The primary realm server requires its satellite servers to authenticate with
usernames in the authorization group ftl-satellite.
ftl-backup
Each realm server requires its backup realm server to authenticate with a
username in the authorization group ftl-backup.
JAAS allows a username to belong to several authorization groups (also known as
roles).
You can suppress the requirements on group membership by specifying the flag
--disable.jaas.groups on page 91.
Realm Server Authentication and Authorization 83
|
Password File
If the realm server enables JAAS authentication and authorization, then you must
configure credentials for FTL components that run as client processes of the realm
server (such as a transport bridge, store server or Rendezvous adapter).
Each such process authenticates itself to the realm server using credentials that it
reads from an ASCII password file (which you specify using the client’s
--password-file command line parameter).
The password file consists of two lines. The first line contains the username. The
second line contains the password string.
The username must be in the JAAS authorization group ftl. For details, see
Realm Server Authentication and Authorization on page 82.
To hide the password from casual observers, you may first obfuscate the
password using tibrealmadmin --mangle.
JAAS Sample Login Modules
TIBCO FTL supports these sample login modules:
•
org.eclipse.jetty.jaas.spi.JDBCLoginModule
•
org.eclipse.jetty.jaas.spi.PropertyFileLoginModule
•
org.eclipse.jetty.jaas.spi.DataSourceLoginModule
•
org.eclipse.jetty.jaas.spi.LdapLoginModule
For more information about login modules and how to configure them, see
http://www.eclipse.org/jetty/documentation/current/jaas-support.html.
See Also
To implement your own login module, see
http://docs.oracle.com/javase/1.5.0/docs/guide/security/jaas/JAASLMDevG
uide.html
84
| Chapter 5
Realm Server
Option and Property Names
The realm server executable files each accept three kinds of options:
•
Short-form command line option—a hyphen with one or two alphabetic
characters (quick to type, but occasionally non-intuitive)
•
Long-form command line option—double hyphen (--) introducing a
descriptive name (longer to type, but usually intuitive)
•
Configuration property
The configuration file has the syntax of a Java properties file.
— To construct a property name, remove the initial double hyphen (--) from
the long-form command line option, and replace them with the prefix
com.tibco.executable_name. For example, in a properties file for the
tibrealmserver utility, the option --data becomes the property
com.tibco.tibrealmserver.data.
— When a command line option acts as a flag (that is, it signals its value by its
presence or absence, rather than a value), the properties file form requires
an explicit value. The value true corresponds to a flag that is present;
false corresponds to absent.
Unique Names
The long-form command line options of the various executables do not conflict.
That is, if the two executables use a parallel option name, they use it in an
identical way.
Furthermore, property names include an explicit namespace (the utility name), so
they can never overlap (between different utilities).
Using the tibrealmserver Executable 85
|
Using the tibrealmserver Executable
Administrators use tibrealmserver (the realm server command line executable)
to start a realm server process.
The realm server must run on a host computer with Java Runtime Environment
(JRE), version 1.7 or later (64-bit).
Most command line parameters and options have both a short and a long form.
The command line parser accepts either form. In addition, you can supply a Java
properties form for most options in a configuration file; see --config on page 93.
Table 21 tibrealmserver Utility (Sheet 1 of 9)
Short
Long
-h
--help
Arguments
Description
Display a help message describing the
command line parameters and options.
Input and Output
-d
--data
path
Optional.
When present, the realm server stores its
working data files in this path location. (The
directory at path must exist; the realm server
does not create it automatically.)
If you run several realm server processes, you
must supply a unique path location for each
server process.
When absent, the default path is the current
directory.
86
| Chapter 5
Realm Server
Short
Long
Arguments
Description
-ht
--http
host:port
Connect Port
Optional.
Clients send initial contact requests to this
web service. The server responds with
information that enables clients to make
requests using the FTL request protocol.
For arguments, you may supply any
combination—host:port, host: or :port.
However, when either --backupto or
--backupfor is also present, you must
explicitly supply both (that is, host:port).
host indicates one of the host computer’s
network interfaces. When host is absent, the
realm server listens for HTTP requests on the
localhost interface. The star character (*)
indicates all available interfaces.
When port is absent, the default value is port
8080.
-f
--ftl
host:port
Client Port
Optional.
Connected clients communicate with the
realm server (using the FTL protocol) over
this service.
network interfaces. When host is absent, this
service uses the same host interface as the
--http connect port. The star character (*)
When port is absent, this service uses a port
number that is 3 greater than the --http
connect port.
|
Short
Long
Arguments
Description
-g
--gui
host:port
Interface Port
Optional.
Browsers send graphic user interface requests
(using the HTTP protocol) to this service. The
realm server responds to web API requests
over this service.
network interfaces. When host is absent, this
service uses the same host interface as the
--http connect port. The star character (*)
When port is absent, this service uses a port
number that is 5 greater than the --http
connect port.
Affiliated Servers
For rules about legal relationships among servers, see Table 19 on page 77.
--backupfor
host:port
When present, start this realm server process
as a potential backup server for a primary or
satellite. (The host:port arguments must match
the arguments to the --http parameter of the
primary or satellite server.)
The primary or satellite server initiates the
backup connection. (You must also configure
that server using the --backupto parameter.)
When present, you must also explicitly
supply --http host:port (with both
arguments).
88
| Chapter 5
Realm Server
Short
Long
Arguments
Description
--backupto
host:port
When present, the server designates a backup
server and attempts to connect to it at
host:port. (The host:port arguments must match
the arguments to the --http parameter of the
backup server.)
(You must also configure the backup server
using the --backupfor parameter.)
While disconnected, this server repeatedly
attempts to connect to its backup.
When present, you must also explicitly
supply --http host:port (with both
arguments).
--satelliteof
host:port
When present, the server designates itself as a
satellite of a primary server. This satellite
server connects to its primary server at
host:port.
A satellite server does not accept client
connection requests until it first receives a
realm definition from its primary server.
A satellite server accepts realm updates only
from its primary. While disconnected, a
satellite server repeatedly attempts to connect
to its primary server.
|
Short
Long
Arguments
Description
-to
--server.timeout
timeout
Optional.
Servers use this timeout (in seconds) for
several purposes:
•
Heartbeat Timeout The server determines
that an affiliated server is unavailable
when its heartbeat signal is silent for this
timeout interval.
•
Connection Timeout The server waits for
this timeout interval before repeating its
connection request to an affiliated server.
Supply a positive number.
When absent, the default value is 3 seconds.
-hb
--server.heartbeat
hb_interval
Optional.
The server sends its heartbeat signal at
hb_interval (in seconds).
Supply a positive number.
When absent, the default value is 1 second.
-u
--server.user
username
Required for affiliated servers when enabling
JAAS.
The server authenticates itself to affiliated
servers with this username. For details, see
Realm Server Authentication and
Authorization on page 82.
When --server.authtobackup.user is present,
the server authenticates itself to its backup
server using that value; however, it still uses
the value of --server.user to authenticate
to satellites.
90
| Chapter 5
Realm Server
Short
Long
Arguments
Description
-pw
--server.password
password
Required for affiliated servers when enabling
JAAS.
The server authenticates itself to affiliated
servers with this password.
To hide the password from casual observers,
you may first obfuscate the password using
tibrealmadmin --mangle.
--server.authtobackup.
username
user
Optional.
When present, the server authenticates itself
to its backup server with this username. For
details, see Realm Server Authentication and
When absent, it uses the value of
--server.user instead.
--server.authtobackup.
password
password
Optional.
When present, the server authenticates itself
to its backup server with this password.
To hide the password from casual observers,
you may first obfuscate the password using
tibrealmadmin --mangle.
When absent, it uses the value of
--server.password instead.
--server.label
label
Optional.
You may supply a string to easily identify the
realm server process within the monitoring
interface. For example, when a primary
server has several satellites, it could be useful
to label them according to their geographic
locations.
If the string value contains space characters,
enclose it in double quote (") characters.
When absent, the default is the host and
HTTP port of the server (see --http on
page 86).
|
Short
Long
Arguments
Description
path
The realm server configures security using
the JAAS configuration file at path.
Security
-j
--jaas
When present, enable JAAS—the realm
server requires and verifies username and
password credentials from client processes,
affiliated servers, transport bridges, browsers
and tibrealmadmin.
When absent, disable JAAS—the realm server
neither requires nor verifies credentials.
For JAAS configuration requirements, see
Realm Server Authentication and
--disable.jaas.groups
When present, the realm server disables
enforcement of the JAAS group requirements,
so that client programs and administrators
can be in any authorization group.
Client programs and administrators must still
have valid username and password
credentials.
This flag lets you use an existing LDAP server
without modifying the group information.
92
| Chapter 5
Realm Server
Short
Long
Arguments
Description
level
When present, the realm server logs FTL
protocol communication at this level of detail.
Supply one of these strings:
Logging
-l
--loglevel
•
off
•
severe
•
warn
•
info
•
verbose
•
debug
The output from debug and verbose can
result in very large log files. This level of
detail is generally not useful unless TIBCO
staff specifically requests it.
When this option is absent, the default value
is info.
--logfile
logfile_prefix
When present, the realm server logs to a
rolling set of log files instead of the console.
The logfile_prefix argument may denote a path
(all of the directories in the path must already
exist).
For more information about rotating log files,
see Log Output Targets in TIBCO FTL
Development.
When absent, the realm server sends log
output to the console, and ignores the
parameters --max.log.size and
--max.logs.
--max.log.size
size
Limits the maximum size (in bytes) of log
files. The value must be greater than 100
kilobytes (102400). The default value is 2
megabytes (2*1024*1024).
|
Short
Long
Arguments
Description
--max.logs
logs
Limits the maximum number of rolling log
files. The default is 50.
path
When present, the realm server reads its
configuration from the file at path.
Configuration File
-c
--config
See Option and Property Names on page 84.
If you specify both a configuration properties
file and command line options, the command
line options override those in the file (where
they conflict).
94
| Chapter 5
Realm Server
Using the tibrealmadmin Utility
Administrators use tibrealmadmin (the realm server utility) to stop, update,
dump or back up a realm server process.
The command line parser accepts either form. In addition, you can supply a Java
properties form for most options in a configuration file; see --config on page 96.
Table 22 tibrealmadmin Utility (Sheet 1 of 3)
Short
Long
-h
--help
Arguments
Description
Display a help message describing the command
line parameters and options.
Connecting to the Realm Server
-rs
--realmserver
url
Required (except with the --mangle command).
Administer the realm server at this location.
url has the form http://host:port, where host and
port correspond to elements of the realm server’s
--gui
-u
--user
username
-pw
--password
password
argument.
Credentials. Required when the realm server
enables JAAS (see --jaas on page 91).
The utility authenticates itself to the realm server
with this username and password.
Commands
Commands are mutually exclusive; you may use only one at a time.
Most commands affect a realm server process that is already running. Specify that realm server
using the --realmserver parameter.
Supply commands only on the command line. It is illegal to supply commands in a configuration
file.
-dr
--dumprealm
path
Write the realm definition to a JSON file at path.
Modifiers: --debug
Using the tibrealmadmin Utility 95
|
Short
Long
Arguments
Description
-ur
--updaterealm
path
Update the realm definition from the JSON file at
path.
The utility replaces the old realm definition (if one
already exists) with the new definition. This
command is available only for the primary server.
Modifiers: --force
-b
--backup_database
Immediately back up the realm server’s database
files.
This command creates a zip file that contains the
relevant files from the server’s data folder. The
name of the zip file incorporates a timestamp.
This command stores the zip file under the server’s
data directory (see --data on page 85), in the
backups subdirectory. You may arrange to copy the
contents of the backups subdirectory to off-site
storage.
-st
-x
--status
Get the status of the realm server and its clients;
output to stdout.
--server_status
Get the status of the realm server—but omit the
status of its clients; output to stdout.
--shutdown
Stop the realm server process.
This command is asynchronous (the utility does not
wait for confirmation that the server has stopped).
To verify that the server has actually stopped, use
the --status command.
96
| Chapter 5
Realm Server
Short
Long
Arguments
Description
--mangle
password
Obfuscate a password to hide it from casual
observers.
You may supply the resulting obfuscated password
as a command line argument to the realm server
(for example, with the --server.password
parameter), or use it in the realm server's
configuration properties file.
This command outputs the obfuscated password to
then exits immediately.
stdout,
(This command ignores the --realmserver
parameter.)
Modifiers
--force
When present along with --updaterealm, break
the realm lock, discarding any undeployed changes
to the realm definition.
--debug
When present along with --dumprealm, dump
additional information for debugging. Use only
when TIBCO support staff request this information.
Configuration File
-c
--config
path
When present, tibrealmadmin reads its
See Option and Property Names on page 84.
If you specify both a configuration properties file
and command line options, the command line
options override those in the file (where they
conflict).
It is illegal to supply commands in a configuration
file; see Commands on page 94.
| 97
Chapter 6
Realm Server and its Browser Interfaces
This chapter introduces the graphical tools that let you interact with the realm
server, and additional details related to those interactions.
The realm configuration interface lets you modify the realm definition, and deploy
changes to the realm server and its client application processes. The realm
monitoring interface lets you monitor and manage clients as they run, and as the
server updates them to a modified realm definition.
Subsequent chapters describe those tools in greater detail.
See Also
TIBCO eFTL™ is documented separately. Administrators use the FTL realm
server GUI to configure and monitor the eFTL service. For information about
these GUI pages, see the documentation set for TIBCO eFTL.
Topics
•
Browser Support, page 98
•
Common Features, page 99
•
Realm (Home Page), page 100
•
Icons, page 101
•
Sidebar, page 104
•
Summary Pages, page 106
•
Restrictions on Names, page 108
•
Size Units, page 109
•
Realm Storage, page 110
•
Modification Lock, page 111
•
The Deploy Transaction, page 112
•
Valid Realm Modifications, page 115
98
| Chapter 6
Browser Support
The realm server graphical user interface supports the browsers in Table 23.
Table 23 Realm Server Browser Support
Browser and Version
Chrome 35
Firefox 29
Internet Explorer 11
Safari 7
Realm Server URL
To access the realm server graphical user interface, use a URL based on this
template:
http://realm_server_host:gui_port
For information about gui_port see Interface Port on page 87.
Common Features 99
|
Common Features
This section describes features common to several pages of the realm server
interface.
Navigation
The large title at the top of each page is the trail of breadcrumbs, which summarizes
the context of the page you are viewing. Breadcrumbs show the shortest path
from the home page to the current page.
Home Logo
The TIBCO FTL logo at the top of each page returns to the main Realm (Home
Page).
Command Icons
Icons in the upper right corner denote commands. The available set of command
icons and their semantics vary, depending on the state and location within the
realm server interface. For complete details, see Icons on page 101.
Auto-Save
The configuration interface automatically saves to the working copy as each
atomic change becomes complete. For example, mouse selections trigger
auto-save, as does shifting the cursor focus away from a text field.
In addition, you can explicitly save to the working copy by clicking the Save
command icon
.
100
| Chapter 6
Realm (Home Page)
The Realm page is the home page of the FTL browser interface. Its main content is
a complete set of icons that navigate to the various tool pages of the interface. For
descriptions of those icons, see Table 24 on page 101.
The navigation icons are organized according to tool usage:
•
Configure & Browse These tool pages let you view and modify various parts
of the realm definition.
•
Manage & Monitor These tool pages let you monitor and manage processes
that operate within the realm, including deployments of updated realm
definitions.
Icons 101
|
Icons
The tables in this section summarize the icons of the realm server graphical
interface.
Table 24 Realm Server Icons—Configure and Browse Commands (Sheet 1 of 2)
Icon
Name
Description
Realm Configure and Deploy Commands
For background information and details, see Realm Storage on page 110.
Lock & Edit
Grab the lock and start editing.
•
Create a modifiable copy of the realm definition, and store it as a
JSON file in the working directory. This copy is equivalent to the
database.
•
Lock the realm definition so only the current user can modify it.
If another user holds the lock, this command fails.
To use this command, users must be in the ftl-admin authorization
group. If you are not in that group, this command fails.
Deploy
Refresh
Finish editing and deploy the modified realm.
•
Auto-save the modified realm definition to the working directory,
and package it as a deployment.
•
Send the deployment package to the realm server. (If the realm server
detects errors in the deployment, it displays the Validation Results
page.)
•
Deploy the new realm definition within a transaction (see The Deploy
Transaction on page 112).
•
If the deployment succeeds, the browser interface releases the lock,
and displays the Deployments page.
Undo modifications and continue editing.
•
Discard undeployed modifications; display the current realm
definition.
•
Retain the lock and continue editing.
102
| Chapter 6
Table 24 Realm Server Icons—Configure and Browse Commands (Sheet 2 of 2)
Icon
Name
Description
Revert
Undo modifications and stop editing.
Save
•
Discard undeployed modifications; display the current realm
definition.
•
Release the lock.
Save modifications to the working directory.
This command does not affect the realm server database.
(The configuration interface frequently auto-saves your modifications to
the working directory. This command lets you force a save.)
Table 25 Realm Server Icons—Maniupulating Items (Sheet 1 of 2)
Icon
Name
Description
Manipulating Items
These general-use icons can appear in several contexts within the interface.
Add
Add or define a new item.
Configure
View the configuration or definition of an item. You may modify the
configuration of an item only if the realm is open for editing.
Reorder
Reorder items (drag and drop this icon).
Delete
Delete an item.
View
View more detail.
Duplicate
Make a copy of an item (as a starting point for defining a similar item).
Icons 103
|
Table 25 Realm Server Icons—Maniupulating Items (Sheet 2 of 2)
Icon
Name
Description
Undo
Undo the previous modification.
Purge
Purge a store or a durable. (This action deletes all messages in the store or
durable.)
Table 26 Realm Server Icons—Monitoring Commands
Icon
Name
Description
Monitoring Icons
For background information, see Chapter 9, Monitoring a Realm, on page 155.
Disable
Disable the selected clients.
Purge
Delete the selected clients or satellites from a list. (The state of the client or
satellites does not change.)
104
| Chapter 6
Sidebar
The sidebar (visible on most pages) speeds navigation to other pages, and
summarizes the realm server’s most important statistics.
Navigating
On pages in the realm configure and browse interfaces, the upper section of the
sidebar contains navigation buttons to other configure and browse pages.
On pages in the realm monitor interface, the upper section of the sidebar contains
navigation buttons to other manage and monitor pages.
Status Summary
The third section of the sidebar summarizes the realm server status at a glance.
(For more detail, see other pages in the realm monitor interface.)
Table 27 Status Summary (Sidebar) (Sheet 1 of 2)
Row
Description
Label or
The label string of this realm server instance. If you did not supply a label when
starting the realm server (using --server.label) this field displays the location
of the realm server instead (see Connect Port and Host:Port).
hostname:port
Sidebar 105
|
Table 27 Status Summary (Sidebar) (Sheet 2 of 2)
Row
Description
Mode
(no label)
For more detail, see the Monitoring the Realm Server.
Realm
Revision
Revision number of the realm definition as stored in the realm server.
Backup For
If the server is a backup server, this field displays the status of its regular server,
and is also a link to the regular server’s home page.
Backup To
If the server has a backup server, this field displays its status, and is also a link to
the backup server’s home page.
Primary
If the server is a satellite server, this field displays the status of its primary, and is
also a link to the primary server’s home page.
Clients
Number of clients.
This number increases each time you deploy modified definitions to the realm
server. This number does not change if the changes do not affect realm semantics
(for example, modifying only a description string).
For details about clients, see the Clients Summary page.
Satellites
Number of satellite servers.
For details about satellites, see the Satellites Summary page.
Uptime
Approximate elapsed time since this realm server process started.
Deployment
Approximate time since the most recent successful deployment to this realm
server.
JVM Memory
Approximate size of the realm server within the Java Virtual Machine. (This
approximation does not include the FTL library, nor the JVM itself.)
106
| Chapter 6
Summary Pages
Summary pages are pages within the realm server graphical interface that display
a list of definitions or entities. This section describes features common to all
summary pages. The configuration interface includes summary pages for
applications, formats and transports. The monitoring interface includes summary
pages for clients and satellites.
Viewing an Item
To view a definition or entity, click its name within the list.
Filtering the List
To view a subset of the items, type characters in the Filter or Create field. The list
narrows to display only those items that contain the character sequence in their
names.
Filters accept standard Java regular expressions using standard JavaScript regular
expressions (we present a subset of the details in Table 28).
Table 28 Filtering Instance Connections—Regular Expression Semantics
Syntax
Description
JavaScript Regular Expression Filtering
.
(dot)
Match any single character.
*
(star)
Match zero or more instances of the preceding element.
+
(plus)
Match one or more instances of the preceding element.
\w
Match any word character.
[chars]
Match any single instance of the characters within square brackets.
Sorting the List
To sort a summary list, click on a column heading. A vertical arrow indicates the
sort order. To reverse the sort order, click the column heading again.
Summary Pages 107
|
Creating a New Definition
To create a new definition, type its name in the Filter or Create field, then click the
Create button or type the Enter key. The new definition appears in the list below.
(This operation is available only when you hold the realm modification lock; see
Modification Lock on page 111.)
Duplicating a Definition
To duplicate a definition (as a starting point for defining a similar item) click the
Duplicate icon
. The browser immediately displays the duplicate item in a
definition page for editing. (This operation is available only when you hold the
realm modification lock.)
Deleting a Definition
To delete a definition, click the Delete icon
corresponding to the definition.
(This operation is available only when you hold the realm modification lock.)
108
| Chapter 6
Restrictions on Names
Reserved Names
All names that begin with an underscore character (_) are reserved. It is illegal for
programs to define formats, fields, endpoints and applications with these
reserved names.
You may use the underscore character elsewhere—that is, where it is not the first
character of a name.
Length Limit
All names are limited to a maximum length of 256 characters.
This limit includes names of formats, fields, endpoints and applications. It also
extends to string values in content matchers.
Size Units 109
|
Size Units
Sizing parameters that accept numeric values also accept unit designators as part
of their arguments. Table 29 presents those units.
Table 29 Size Units
Unit
Designates
Example
none
bytes
2048
KB, K
kilobytes
100KB
MB, M
megabytes
500MB
GB, G
gigabytes
1GB
110
| Chapter 6
Realm Storage
Each realm server stores the definition of exactly one realm; however, it stores the
realm definition in several different ways—which interact with commands in the
browser interface.
The canonical realm definition resides in the realm server database.
The browser interface uses private working copies of the realm definition (in
JSON format) as intermediate storage while administrators modify the realm
definition. The browser always displays a working copy.
The browser interface also caches a copy of each update of the realm definition to
a deployment directory.
Figure 11 illustrates the stored forms of a realm, and the commands that transition
among them (colored arrows). Numbered arrows in Figure 11 refer to transaction
steps in the Deploy command (for further details, see The Deploy Transaction on
page 112).
Each command begins in the browser, and flows to the realm server, which
executes the command. During command execution, all data flows through the
realm server. (We have simplified some arrows in Figure 11 to make the diagram
more readable; nonetheless, everything flows through the realm server.)
Figure 11 Realm Storage and Commands
Save;
Auto-Save
Configuration
Interface
(Browser)
Lock & Edit;
Refresh;
Revert
Deployment
Directory
4
Working
Directory
Realm
Server
Deploy
2
Clients
1
3
Realm Server Database
Modification Lock 111
|
Modification Lock
The realm definition is protected by a lock file, so that only one user at a time may
modify it.
The realm configuration interface always displays part of the realm definition. If
you hold the lock, then the interface lets you modify the definition. If you do not
hold the lock, the interface is read-only.
To grab the lock and edit the realm definition, users must be in the ftl-admin
authorization group.
The lock is not required for management operations, such as purging durables
from a persistence store, or saving the state of persistence servers.
Lock & Edit Command
The Lock & Edit command attempts to grab the lock. If another user already
holds the lock, you can choose one of three options:
•
Break. Reject the other user’s modifications. Grab the lock, and begin editing
with a realm definition equivalent to the realm server database.
•
Take. Accept the other user’s modifications as a starting point. Grab the lock,
and begin editing with a realm definition that reflects the other user’s
modifications.
The dashed yellow line in Figure 11 does not apply with this option. At a later
time, if you decide to discard the other user’s modifications, you can use the
Refresh command to begin again with a realm definition equivalent to the
database.
•
Cancel. Leave everything as it stands.
Refresh and Revert Commands
In Figure 11 and Table 24, notice that after either the Refresh command or the
Revert command, the configuration interface displays a realm definition
equivalent to the realm server database. These commands differ in their effect on
the realm modification lock.
112
| Chapter 6
The Deploy Transaction
The Deploy command initiates a transaction (see the steps below), with the goal
that all clients begin using the modified realm definition.
A dialog box offers options:
•
Deploy attempts to execute all the transaction steps, and displays the results
on the Deployments page.
•
Test Deployment attempts to execute only step 1, and displays the results on
the Deployments page.
Transaction Steps
Step numbers correspond to numbered arrows in Figure 11 on page 110.
1. Test the deployment against all connected client application processes. (If the
realm server is a primary with satellites, see Satellite Servers Recursively Test
Their Clients on page 113.)
The server also tests the connection to its backup server (if one is configured).
If it is disconnected, then rollback the transaction.
Each client tests the modified realm definition to determine whether it can
accept the modifications and continue running. Each client reports its
response to the realm server (see Responses to Deployment Tests, below). The
server combines the answers from its clients, and reports a single consolidated
answer (see Consolidating Responses, below).
If the consolidated test succeeds (see Successful Test, below), or an
administrator intervenes with a Proceed option, then proceed to the next step;
otherwise rollback the transaction.
2. Write the modified realm definition to the realm server database.
3. Instruct client application processes to begin using the modified realm
definition.
4. Copy the deployment package from the working directory to a deployment
directory (archive).
5. Release the realm modification lock.
The Deploy Transaction 113
|
Responses to Deployment Tests
Table 30 lists the possible responses after testing a realm update deployment,
from most favorable to least favorable.
Table 30 Responses after Testing a Modified Realm Definition
Response
Description
Yes
The client can accept the modifications, and continue running.
Requires
The current client process cannot accept the modifications, but restarting the
client process would resolve the issue.
Restart
The client program cannot accept the modifications. (Even restarting the client
process would not suffice to resolve the issue.)
No
See Also
Valid Realm Modifications, page 115
Consolidating Responses
A server consolidates the responses from all of its clients. The primary server
consolidates the responses from all of its clients and all of its satellite servers.
The consolidated response is the least favorable response reported by any client or
satellite server. For example, if 77 clients report Yes, and one client reports
Requires Restart, then the consolidated response is Requires Restart. If
even one client were to report No, then the consolidated response would be No.
Satellite Servers Recursively Test Their Clients
Satellite realm servers broaden step 1 of the deploy transaction (above). The
primary server not only tests the deployment against its own clients, it also tests
the deployment against each of its satellite servers—which, in turn, test the
modified realm definition against their clients (and backup servers). Each of these
clients determines whether it can accept the modifications and continue running;
each client reports its answer to the satellite server. Each satellite server combines
the answers from its clients, and reports a single consolidated answer to the
primary.
The primary consolidates the answers from its clients and satellites, using the
same rules in Consolidating Responses, above.
114
| Chapter 6
Successful Test
If the consolidated response is Yes, then the transaction proceeds to step 2.
Unsuccessful Test
If the consolidated response is anything other than Yes, then the browser interface
displays the Action Status panel (see Active Deployment Request on page 170).
The administrator must intervene by selecting one of the options in Table 31.
Table 31 Action Status Options
Option
Description
Cancel
The transaction rolls back. The realm server and its clients discard the modified realm
definition, and continue as they were.
Proceed
The transaction proceeds to step 2. When the transaction commits, the realm server
stores the modified realm definition in the database, and instructs the clients that can
accept it to begin using it. Clients that cannot accept it continue running as they were
(problems might arise as those clients interact with updated clients).
Wait
Sometimes the realm server cannot communicate with one or more clients. In this
situation you can wait for more clients to respond (or select one of the options above).
Meanwhile, the transaction remains at step 1.
After waiting a maximum of 10 minutes, the primary realm server automatically
cancels and rolls back the deploy transaction (which allows new clients to connect to
the realm server).
Backup Prevents Satellite Update
A backup server is tightly coupled to its regular server, but a satellite is only
loosely coupled to its primary server. As a result, a backup server B to a satellite S
can prevent primary server P from updating S, but S cannot prevent P from
updating itself and its other satellites. If B is unavailable when P attempts to
update S, then S will remain out of sync with P until B again becomes available.
Valid Realm Modifications 115
|
Valid Realm Modifications
Table 32 describes the ways in which you can modify the realm definition, and the
consequences of each modification.
Table 32 Realm Modifications and Deployments (Sheet 1 of 6)
Modification
Details
Application Definition Modifications
Add applications
You can add a new application definition.
Delete applications
You can delete an application definition from the realm definition. All
client instances of that application implicitly become invalid (though they
continue to run). You must explicitly stop or disable those client processes
(see Disabling Clients, page 164).
Manage All Formats
If you modify the application parameter Manage All Formats, then
clients could require restart. In particular, if the modification changes an
application’s effective value of this parameter, then all instances of that
application require restart.
Format Modifications
Add formats
You can add a new managed format to an application definition.
You can also upgrade a dynamic format to a managed format, in order to
gain efficiency. When upgrading, the managed format must exactly
match the existing dynamic format (that is, format name, field names,
and field types); it may also include additional fields that are not in the
existing dynamic format.
For a client to use a new managed format, you must also add that format
to the application’s preload formats list.
Add preload format
You can add preload formats to an application definition.
116
| Chapter 6
Modification
Details
Add fields
You can add fields to an existing format definition.
We recommend adding fields only to the end of an existing format (that is,
after all its existing fields).
Delete fields
•
Conforming to this rule permits graceful migration of client processes
from the old format definition to its new definition. As each client
restarts, it begins using the new definition, and the new fields become
accessible. Meanwhile, clients using different versions of the format
definition can still exchange messages with that format.
•
Violating this rule is disadvantageous. All clients that use the format
require restart—and they all must restart in synchrony. Clients that
use one version of the format definition cannot recognize messages
that use another version, and silently discard them.
You can delete a field from an existing format definition. All clients that
use the format require restart—and they all must restart in synchrony.
Clients can recognize older format versions only if they received those
versions during their initial preload from the realm server. Clients silently
discard messages with unrecognized formats.
Endpoint Modifications
Add endpoints
You can add new endpoints to an application definition.
Delete endpoints
You can delete an endpoint from an application definition. If a client has
publisher or subscriber objects on that endpoint, then the client requires
restart.
Transport Modifications
Add transports
You can add new transports to an application definition.
|
Modification
Details
Delete transports
You can delete an existing transport definition. Client processes
immediately stop using the bus on the affected transport:
•
Send to inbox calls raise an exception (when the inbox is no longer
accessible).
•
Send one-to-many calls return normally, but the deleted transport
does not carry messages. (If an endpoint still has other operating
transports, then they continue to carry messages; otherwise the
endpoint silently discards messages.)
•
Subscribers silently stop delivering messages from the deleted
transport.
Modify transport
parameters
You can modify the parameter values of a transport. If an application
instance binds an affected transport, then it requires restart.
Add or delete
transport relationships
You can add or delete a transport relationship.
Application Instance Modifications
Add transports to
endpoints
You can add a transport to implement an existing endpoint in an
application instance. Existing process instances immediately bind the
new transport to implement the endpoint, and attempt to establish a bus.
Some transports require the application process to restart (in order to
establish their bus).
Delete transports from
endpoints
You can delete a transport from an endpoint (in an application instance).
Client processes immediately stop using that transport to implement that
endpoint:
•
accessible).
•
Send one-to-many calls return normally, but the deleted transport
does not carry messages. (If the send ability still has other operating
transports, then they continue to carry messages; otherwise the
endpoint silently discards messages.)
•
Subscribers silently stop delivering messages from the deleted
transport.
118
| Chapter 6
Modification
Details
Enable or disable
abilities
You can enable or disable transport abilities of an endpoint in an
application instance.
Communications on the endpoint immediately expand to use the
additional ability.
A disabled ability immediately stops carrying messages:
•
accessible).
•
Send one-to-many calls return normally, but the transport’s send
ability does not carry messages. (The endpoint silently discards
messages.)
•
The transport’s receive and receive inbox abilities silently stop
delivering messages.
Realm Property Modifications
Modify realm
properties
You can modify any realm property.
If you modify the realm property Manage All Formats, then some
clients could require restart. In particular, if the modification changes an
application’s effective value of this parameter, then all instances of that
application require restart.
Store and Durable Modifications
Add or delete stores
You can add, rename or delete a store.
When deleting or renaming a store, all store server processes require
restart. You must first stop all the servers, then restart all servers (note that
this resets the cluster’s data state to empty).
To avoid data reset, you can delete all the durables from a store, instead of
deleting the store itself. (You can delete the store later, at a time when
data reset is acceptable.)
Before deleting a store, you must first review every application definition
in the realm, ensuring that none of the endpoints still refer to the store
you plan to delete.
Add or delete durables
You can add durables to a store, or delete durables from a store.
(When deleting a durable from a store, you must also remove subscriber
name mappings to that durable.)
|
Modification
Details
Modify store or
durable parameters
You can modify parameter values of stores and durables.
When modifying the publisher mode of a store, or the acknowledgement
mode of a durable, all affected clients disconnect from the cluster (that is,
the leader) and automatically reconnect.
From the moment that a subscriber object first interacts with a durable,
you may no longer change a durable’s message interest, nor its matcher
fields. If these configuration values must subsequently change, you can
instead map the subscriber to a new durable with the correct message
interest and matcher fields.
Modify the mapping
from subscriber names
to durables
You can modify the mapping from subscriber names to durable names for
an endpoint. All clients that have durable subscribers on that endpoint
require restart.
Add or delete store
servers
You can add or delete a store server.
The cluster temporarily becomes unavailable while reforming a quorum.
Ensure that adding or deleting a store server does not prevent forming a
quorum.
When adding a server, we recommend assigning it a low weight, so that it
does not immediately become the leader. You can raise its weight later—
after it replicates the cluster’s message data.
Changing the name of a store server is like deleting it, and replacing it
with a new one. The store server process requires restart.
Modify cluster
transport parameters
of a store server
Modify client transport
parameters of a store
server
You can modify cluster transports of store servers.
When modifying even one cluster transport or any of its parameters, all
store servers require restart. You must first stop all servers, then restart all
servers (note that this resets the cluster’s data state to empty).
You can modify client transports of store servers.
When modifying a primary client transport or any of its parameters, that
store server and all its clients require restart. If you modify the client
transports of several servers, we recommend that you stop and restart
them one at a time, so that the cluster retains its data state.
120
| Chapter 6
Modification
Details
Modify alternate client
transport parameters
of a store server
You can modify alternate client transports of store servers.
Adding an alternate client transport (when it was not previously
configured) does not require restart. Clients can connect using that
transport immediately following successful deployment.
Deleting an alternate client transport does not require restart. Clients
cannot connect (nor reconnect) using the deleted transport. However,
existing clients can remain connected on the deleted transport.
Modifying the transport parameters of an alternate client transport
requires restart of the store server and the clients that connect using the
modified transport.
You can add and delete associated client host names. The store server
does not require restart. Clients on added hosts can connect using the
alternate client transport immediately following successful deployment.
A client on a deleted host remains connected until the client restarts.
See Also
Responses to Deployment Tests, page 113
| 121
Chapter 7
Configuring a Realm using the GUI
This chapter presents the graphical configuration interface that lets you define
and configure a realm.
(To configure a realm using Python-based scripts, see Chapter 10, Configuring a
Realm using Python Scripts, on page 177.)
Topics
See Also
•
Applications Summary, page 122
•
Configuring an Application Definition, page 123
•
Configuring an Application Instance, page 127
•
Transports Summary, page 130
•
Configuring a Transport Definition, page 131
•
Formats Summary, page 135
•
Configuring a Format Definition, page 136
•
Configuring the Realm Properties, page 139
To configure stores and durables, see these sections in Chapter 15:
•
Configuring the Realm Persistence Cluster, page 270
•
Configuring a Persistence Server Definition, page 272
•
Configuring a Store Definition, page 275
•
Configuring a Durable Definition, page 277
•
Configuring Persistence Stores within the Application Definition, page 280
•
Configuring Durable Subscribers within an Application Instance, page 281
To configure the eFTL service, see TIBCO eFTL User’s Guide.
122
| Chapter 7
Applications Summary
The Applications summary page lists application definitions in the realm, and lets
you create new application definitions.
See Also
Configuring an Application Definition 123
|
Configuring an Application Definition
The Application definition page presents the details of an application definition,
and lets you modify the definition.
124
| Chapter 7
Table 33 Application Definition—Components (Sheet 1 of 3)
Parameter
Description
Name
Required.
Name of the application.
Application names must be globally unique within the realm.
Description
Optional.
You can use this text field as a comment to describe the application
and attach administrative notes.
Configuring an Application Definition 125
|
Parameter
Description
Manage All Formats
Restrict the formats available to an application.
When enabled, the only available formats are preload formats and
built-in formats. For complete information, see Restricting Formats on
page 141.
Endpoints
Define the endpoints of the application.
When the application defines only the default instance, you can add and configure endpoint
transport connectors in the Default Transport Connectors sections, and the endpoint subscriber
names (for mapping to durables) in the Default Subscribers sections.
Endpoint Name
Required for each endpoint.
Store
Optional for each endpoint.
To associate an endpoint with a store, add the store name here. For
details, see Configuring Persistence Stores within the Application
Definition on page 280.
Application Instances
Define the instances of the application.
You must configure the default application instance (and you cannot
delete it). You may also define other application instances (optional).
When the application defines only the default instance, you can add
and configure endpoint connectors and subscriber names on this page.
If the application defines additional instances, then this section
displays a list of the instances. You can configure the endpoint
connectors of an instance on its application instance page (including a
separate page for the default instance); see Configuring an
Application Instance on page 127.
For an overall conceptual explanation of instances and connectors, see
Implementation—Application (Macro) on page 23.
The icons (at left of each instance) indicate whether the instance
defines transport connectors, and whether it maps durable subscriber
names.
126
| Chapter 7
Parameter
Description
Preload Formats
Determines the set of format definitions that the application receives
from the realm server when the process instance starts (and which the
process caches in its realm object). This parameter also determines the
set of defined formats that an application can use.
Each format name must be defined as a format in the realm.
See Also
Configuring an Application Instance 127
|
Configuring an Application Instance
The Application Instance definition page presents the details of an application
instance definition, and lets you modify the definition.
128
| Chapter 7
Table 34 Application Instance Definition—Components (Sheet 1 of 2)
Parameter
Description
Instance Name
Required.
Name of the application instance.
Instance names must be unique within each application. (You may use the same
instance name in several different applications.)
The default instance always has the instance name default; you cannot change it.
Description
Optional.
You can use this text field as a comment to describe the application instance and
attach administrative notes.
Host
Optional.
Hostname or IP address for matching.
When present, the Transports (Endpoint Connectors) apply only to process
instances running on this host. To match, this string value must exactly match
either the output of the hostname operating system call on the computer where
the application process is running, or the IP address bound to that hostname.
For an explanation of matching, see Implementation—Application (Macro) on
page 23.
Identifier
Optional.
Identifier string for matching.
When present, the Transports (Endpoint Connectors) apply only to process
instances that supply this identifier when connecting to the realm server. The
identifier must match exactly.
For an explanation of matching, see Implementation—Application (Macro) on
page 23.
Configuring an Application Instance 129
|
Table 34 Application Instance Definition—Components (Sheet 2 of 2)
Parameter
Description
Transports (Endpoint Connectors)
For each of the application’s endpoints, this page displays a corresponding endpoint connector
panel. The title of each endpoint connector panel is the name of the endpoint that it configures.
You must connect each endpoint to at least one transport. For background information, see
Implementation—Endpoints (Micro) on page 20.
To create a connector, click the Add a Transport icon.
Transport
Name
Endpoint
Ability
Check-Boxes
Required.
Each connector binds an endpoint to a transport. You must supply a valid
transport name. For background information, see Chapter 3, Implementing
Endpoints, on page 15.
Receive
Send
Receive Inbox
Send Inbox
Each connector specifies the endpoint abilities that the transport carries. You must
check at least one ability box. For details, see Abilities on page 18, and
Implementation—Endpoints (Micro) on page 20.
Subscribers
For each of the application’s endpoints, this page displays a mapping from subscriber names to
durables. The title of each subscriber panel is the name of the endpoint that it configures.
For details, see Configuring Durable Subscribers within an Application Instance on page 281.
To create a connector, click the Add a Subscriber icon.
See Also
130
| Chapter 7
Transports Summary
The Transports summary page displays transport definitions in the realm, and
lets you create new transport definitions.
For each transport definition, the summary displays the transport name, and its
transport type in square brackets. You can filter by type by including brackets in
the filter string. (Brackets have special meaning in regular expression syntax; to
avoid this meaning, precede brackets with escape characters.)
See Also
Configuring a Transport Definition 131
|
Configuring a Transport Definition
The Transport definition page presents the details of a transport definition, and
lets you modify the definition.
It is erroneous to define two transports with identical configurations.
132
| Chapter 7
Table 35 Transport Definition—Components (Sheet 1 of 2)
Parameter
Description
Common Components
Name
Required.
Name of the transport.
Transport names must be globally unique within the realm.
Description
Optional.
You can use this text field as a comment to describe the transport and
Transport Type
Required.
Select one of the available transport types.
For detailed descriptions of the available transport types, see
Chapter 4, Transports, on page 35.
Additional Components
transport parameter fields
Other fields (described elsewhere) represent parameters that are
specific to the various transport types. For explanations of the
parameters for each transport type, see Chapter 4, Transports, on
page 35.
Related Transports
This pane (see screenshot below) appears only when the transport
type allows fragmentary transport definitions.
Transport types that are not inherently unitary allow relationships
between transports; see Transport Relationships on page 38. Transport
relationships are symmetric—if you configure a relationship from T1
to T2, then the configuration interface automatically records the
reciprocal relationship from T2 to T1.
Configuring a Transport Definition 133
|
Table 35 Transport Definition—Components (Sheet 2 of 2)
Parameter
Description
Advanced Settings
Non-Blocking Send
This check-box governs the behavior of the transport when the bus is
full (that is, it cannot accept any more outbound messages).
When enabled (the default), and the bus is full, the transport holds
outbound messages in a backlog buffer (in process memory) until the
bus can accept them.
When disabled, and the bus is full, the transport blocks send calls in
the program.
For more information, see Blocking vs Non-Blocking Send on page 47.
Backlog Buffer Size
Required when Non-Blocking
Send
is enabled.
This parameter determines the size (in bytes) of the backlog buffer.
The default value is 64 megabytes.
With zero bytes of backlog buffer, a non-blocking send call
immediately discards its message if the transport cannot accept
outbound data.
Receive Spin Limit
This parameter governs blocking behavior of threads when waiting
for message data to arrive. The default value is 0.01 seconds.
Do not adjust this parameter unless you thoroughly understand the
material in Receive Spin Limit on page 50.
Edit Configuration
Manually
See Also
Do not use this feature except as directed by TIBCO Support personnel.
For details, see Edit Configuration Manually on page 134.
134
| Chapter 7
Edit Configuration Manually
Do not use this feature except as directed by TIBCO Support personnel.
If you need to view any part of the realm definition as a JSON string (but do not
need to modify it), see instead Realm Source on page 154.
Selecting this check-box lets you edit the transport definition as a JSON string.
However, once you enable this feature, the realm server constrains your
subsequent choices.
•
The realm server enforces correct JSON syntax, but does not verify semantics.
•
The realm server does not parse the JSON string to extract values for the GUI
fields.
•
Turning off this feature does not return to the original GUI configuration of the
transport. Instead, it supplies a default transport configuration (which is a
shared memory transport with default values for the required parameters).
To return to the original GUI configuration, you may use the Refresh
command (discard all realm modifications).
Formats Summary 135
|
Formats Summary
The Formats summary page displays format definitions in the realm, and lets you
create new format definitions.
Show Historic Formats
When you modify a format definition by deleting a field, the realm server creates
a new version of the definition, and retains the old version. The realm server
retains older versions so that durable subscribers can still receive messages (that
use older format versions) from the store.
The formats summary list does not ordinarily display superceded versions;
however, to display those older versions, you can enable the checkbox Show
Historic Formats.
If you are certain that an old format version is no longer relevant (that is, all
publishing applications and all messages within stores no longer use that
version), you may explicitly delete that version.
See Also
136
| Chapter 7
Configuring a Format Definition
The Format definition page presents the details of a format definition, and lets
you modify the definition.
Table 36 Format Definition—Components (Sheet 1 of 2)
Parameter
Description
Name
Required.
Name of the format.
Format names must be globally unique within the realm.
Description
Optional.
You can use this text field as a comment to describe the format and
Configuring a Format Definition 137
|
Table 36 Format Definition—Components (Sheet 2 of 2)
Parameter
Description
Fields
Required.
Define the fields of the format.
Each field consists of a name and a type.
Field names must be unique within each format. (You may use the
same field name in several different formats.)
Select the field’s type from the drop-down menu. For descriptions of
the datatypes, see Table 37, below.
Table 37 Field Datatypes
Type Name
(in Realm)
Type Constant
(in Programs)
Description
long
TIB_FIELD_TYPE_LONG
A long integer.
long_array
TIB_FIELD_TYPE_LONG_ARRAY
An array of long integers.
double
TIB_FIELD_TYPE_DOUBLE
A double-length floating point number.
double_array
TIB_FIELD_TYPE_DOUBLE_ARRAY
An array of double-length floating
point numbers.
string
TIB_FIELD_TYPE_STRING
A UTF-8 string.
string_array
TIB_FIELD_TYPE_STRING_ARRAY
An array of UTF-8 strings.
opaque
TIB_FIELD_TYPE_OPAQUE
An opaque byte-array.
message
TIB_FIELD_TYPE_MESSAGE
An FTL message (that is, the field’s
value is a sub-message).
message_array
TIB_FIELD_TYPE_MESSAGE_ARRAY
An array of FTL messages.
inbox
TIB_FIELD_TYPE_INBOX
An inbox.
datetime
TIB_FIELD_TYPE_DATETIME
An FTL DateTime value.
datetime_array
TIB_FIELD_TYPE_DATETIME_ARRAY
An array of FTL DateTime values.
138
| Chapter 7
See Also
Configuring the Realm Properties 139
|
Configuring the Realm Properties
The Realm Properties configuration page presents the values of realm properties,
and lets you modify the property values.
140
| Chapter 7
Table 38 Realm Parameters
Parameter
Description
Description
You can use this text field as a comment to describe the realm and attach
administrative notes. Optional.
Client-Server
Heartbeat Interval
The realm server instructs its clients to send it heartbeats at this interval
(in seconds).
Zero is a special value, instructing the clients not to send heartbeats.
Server Timeout Client
When a realm server does not receive client heartbeats for this interval,
the server deletes the client from list of monitored clients.
Server-Client
Heartbeat Interval
The realm server sends heartbeats to its clients at this interval (in
seconds).
Zero is a special value, instructing the realm server not to send heartbeats.
Client Timeout Server
When a client does not receive server heartbeats for this interval, it
actively attempts to reconnect to a server. If the server has a fault-tolerant
partner, the client can failover to that partner.
Client Monitoring
Sample Interval
Clients sample their operating statistics at this interval (in seconds).
Zero is a special value, instructing all clients to disable the monitoring
feature.
For background information, see Chapter 11, Client Monitoring, on
page 181.
Manage All Formats
Restrict the formats available to an application.
When enabled, the only available formats are preload formats and
built-in formats. For complete information, see Restricting Formats on
page 141.
Restricting Formats 141
|
Restricting Formats
For efficiency and for safety, administrators can use the Manage All Formats
parameters to restrict the formats available to some or all of the applications in a
realm. That is, administrators can require that applications use only preload
formats and built-in formats, and prohibit applications from using dynamic
formats.
Configuration
Twin parameters determine whether this prohibition is in effect; these parameters
both have the same name, but they apply with different scope. One applies only
to the instances of a specific application; the other applies to all applications
throughout the realm.
While administrators can configure these parameters independently, the effective
value governing an application is the inclusive OR (IOR) of the parameter in both
scopes. That is, if either the realm or the application restricts formats, then the
restriction is in force for the application.
•
To restrict formats only in a specific application, fill the check-box Manage
Formats (check-box filled) on that application’s definition page.
•
To restrict formats in all applications, fill the check-box Manage
on the realm properties page.
•
To permit formats without restriction in an application, both check-boxes must
be empty (that is, the realm property and the application parameter).
All
All Formats
The default value of this parameter is false (check-box empty) for new application
definitions and also for new realm definitions. (Application definitions receive the
same default value when migrating from release 2.0.)
See Also
Background information: Formats—Managed, Built-In and Dynamic, page 10.
Changes require restart: Valid Realm Modifications, page 115
Application parameter: Manage All Formats, page 125
Realm property: Manage All Formats on page 140
142
| Chapter 7
| 143
Chapter 8
Browsing a Realm using the GUI
This chapter presents the graphical tools that let you browse a realm, and view it
from different perspectives.
Topics
•
Validation Results, page 144
•
Instance Connections, page 145
•
Transport Relationships, page 152
•
Realm Source, page 154
144
| Chapter 8
Validation Results
The configuration interface validates modifications as you make them (that is, at
every save and auto-save operation). The realm server also validates when you
deploy.
When validation detects any configuration errors, this page reports them. A
numeric badge in the sidebar indicates the total number of detected errors and
warnings.
Next to each reported error is a View icon, which displays the configuration page
where that error occurs.
Table 39 presents general categories of configuration errors that the realm server
detects during validation.
Table 39 Realm Configuration Errors
Configuration Errors
Two or more items with the same name.
References to named items that are not defined in the realm.
Duplicate references to items that must be unique.
Required fields that are empty, missing or undefined.
Transports with invalid values for configuration parameters.
See Also
Instance Connections 145
|
Instance Connections
The Instance Connections page displays a connectivity graph visualizing the
connections (as configured) between endpoints in application instances and the
transports that implement them.
The graph shows connections as configured in the realm definition. You can use it
to diagnose configuration errors, but not hardware or network errors.
Connections at Work
Internally, each process instance manifests instance connections within its
endpoint instances (that is, publisher or subscriber objects). Neither programmers
nor administrators have direct access to these instance connections.
Operationally, each instance connection represents a pathway for data to flow into
an application process—or out from it—through one of its endpoint instances.
Example 1 Instance Connections Graph for Request-Reply Sample Applications
Figure 12 on page 146 depicts a subset of the instance connections among the
endpoints and transports in the sample realm, for use in the applications
tibrequest and tibreply.
The program tibrequest sends one-to-many messages through
The program tibreply receives those messages through
tibreply-endpoint, and sends one-to-one replies back through the same
endpoint. The program tibrequest receives those replies through
tibrequest-endpoint.
tibrequest-endpoint.
In default instances of these application programs, a common transport
(shm-requestreply-tport) implements the two endpoints, connecting the two
programs with a shared communication path.
In rdma instances of these application programs, a pair of related transports
(rdma-request-tport and rdma-reply-tport) implement the two endpoints,
connecting the two programs with a shared communication path.
146
| Chapter 8
Figure 12 Application Instance Connections Graph
|
Figure 13 Application Instance Connections Graph with Store
Understanding the Instance Connections Graph
The instance connections graph consists of vertices and edges. The vertices are
arranged in two columns, with edges crossing between the columns.
Table 40 Instance Connections Graph, Iconography (Sheet 1 of 2)
Glyph
Description
Green circle vertices in the left column represent endpoints in application instances
(grouped by application name).
•
Large labels represent application names (for grouping endpoints). To view the
definition page of an application, shift-click the application’s label.
•
Smaller labels represent endpoints, and have the form endpoint@instance_name.
To highlight the full connection path from or to an endpoint instance, click the endpoint’s
instance label or its green circle vertex; see Visualizing Specific Connections on page 148.
Gray ball vertices in the right column represent transports.
Labels represent transport names.
To view the definition page of a transport, shift-click the transport’s label or its gray ball
vertex.
Gray box vertices in the right column represent stores.
Labels represent store names.
To view the definition page of a store, shift-click the store’s label or its gray box vertex.
148
| Chapter 8
Table 40 Instance Connections Graph, Iconography (Sheet 2 of 2)
Glyph
Description
Straight black edges between the two columns represent connectors—visually linking
endpoints with the transports that implement them.
A black arrowhead indicates that a connector binds its transport to a one-to-many
ability. (Messages flow toward the arrowhead.)
•
An arrowhead near the transport column (pointing right) indicates a send
ability.
•
An arrowhead near the endpoint column (pointing left) indicates a receive
ability.
A black dot-head indicates that a connector binds its transport to a one-to-one
ability. (Messages flow toward the dot-head.)
•
A dot-head near the transport column (on the right) indicates a send inbox
ability.
•
A dot-head near the endpoint column (on the left) indicates a receive inbox
ability.
Curved edges to the right of the transport column represent relationships between
transports.
Visualizing Specific Connections
In a large or complex graph it is sometimes difficult to see the way in which
individual connections unite to form a path for messages.
To highlight the full path from or to an endpoint instance, click its label or its
green circle vertex. All other connections, endpoints and transports fade to gray,
so you can clearly see a specific path (see Figure 14).
|
Figure 14 Application Instance Connections Graph, Highlighting Specific Connections
To highlight a different path, click one of its endpoint instances.
To remove highlighting, click one of the highlighted endpoint instances.
To view the definition of an application or a transport, double-click its name.
(This feature is not available for group and bridge definitions.)
Filtering Instance Connections
The instance connections page supports standard JavaScript regular expressions,
supplemental instance filtering syntax (see Table 41) and display modifiers (see
Table 42).
Table 41 Filtering Instance Connections—Regular Expression Semantics (Sheet 1 of 2)
Syntax
Description
Instance Filtering Syntax
This filtering syntax applies only on the instance connections graph.
@
Match specific elements within the endpoint name. Endpoint names have this
implicit syntax: endpoint@instance@application. You may omit the application element.
When an @ character is present, the filter applies only to extended endpoint
names, and not to transport names.
150
| Chapter 8
Table 41 Filtering Instance Connections—Regular Expression Semantics (Sheet 2 of 2)
Syntax
Description
space
Combine filter elements with logical OR semantics.
-
(not)
Invert the sense of the following filter element.
For example, -mcast matches any item that does not contain the string mcast.
JavaScript Regular Expression Filtering
This filtering syntax applies to the instance connections graph, and also to summary pages (see
Filtering the List on page 106).
.
(dot)
Match any single character.
*
(star)
Match zero or more instances of the preceding element.
+
(plus)
Match one or more instances of the preceding element.
\w
Match any word character.
[chars]
Match any single instance of the characters within square brackets.
Table 42 Filtering Instance Connections—Display Modifiers (Sheet 1 of 2)
Display Modifier
Description
Filter Endpoints Related
Via Transports
Control the degree of filtering.
When checked, filter the graph strictly, so you can more easily locate
items of interest. Apply the filter to both endpoint names and transport
names. Display endpoints only if they match.
When unchecked, filter the graph leniently, so you can see complete
paths from endpoint to endpoint. Apply the filter only to transport
names. Display endpoints that match, or are connected to displayed
transports (even if the endpoints do not match the filter).
With either setting, the graph displays transports that match, or are
connected to endpoints that match, or are related to other displayed
transports.
Hide Transports/Stores
with No Endpoints
When checked, hide unused transports.
When unchecked, show all matching transports.
|
Table 42 Filtering Instance Connections—Display Modifiers (Sheet 2 of 2)
Display Modifier
Description
Hide Endpoint with No
Transports
When checked, hide unbound endpoints.
Show Send & Receive
When checked draw arrowhead connectors representing one-to-many
abilities.
When unchecked, show all matching endpoints.
When unchecked, hide one-to-many abilities.
Show Send Inbox &
Receive Inbox
When checked draw dot-head connectors representing one-to-one
abilities.
When unchecked, hide one-to-one abilities.
152
| Chapter 8
The Transport Relationships page displays a connectivity graph visualizing the
links among related transports. You can use the graph to quickly understand the
relationships among transports in the realm.
The graph shows relationships as configured in the related transport section of
transport definitions—not the actual shared communication path among the
related transports.
The screenshot shows the sample realm, filtered to show only those transports
whose transport name contains the string req, plus any other transports that are
related to the filtered set. Notice that RDMA and RUDP transports are related in
pairs—the connecting end at the request transport, and the listening end at the
reply transport. In contrast, the shared memory transport definition
(shm-requestreply-tport) is unitary, and cannot participate in a relationship
with other transports.
Transport Relationships 153
|
Each green dot is a hyperlink to the transport definition page of the
corresponding transport.
For background information, see Transport Relationships on page 38.
To configure transport relationships, see Transport Relationships on page 132.
154
| Chapter 8
Realm Source
The Realm Source page displays the realm definition in JSON format. It does not
permit you to edit that definition.
Browser search mechanisms can find strings within the definition.
| 155
Chapter 9
Monitoring a Realm
This chapter presents the graphical tools that let you monitor a realm and manage
its clients.
Topics
See Also
•
Overview, page 156
•
Monitoring the Realm Server, page 157
•
Clients Summary, page 160
•
Monitoring a Client, page 161
•
Disabling Clients, page 164
•
Satellites Summary, page 165
•
Deployments, page 168
•
Active Deployment Request, page 170
•
Last Deployment Request, page 173
•
Recent Deployments, page 174
To monitor advanced features, such as groups, transport bridges and stores, see
the chapters that present those features:
•
Group Server Monitoring Page, page 220
•
Bridge Monitoring Summary, page 244
•
Bridge Status, page 245
•
Persistence Servers Monitoring Summary, page 283
•
Monitoring a Persistence Server, page 286
•
Persistence Stores Monitoring Summary, page 289
•
Monitoring a Store, page 290
To monitor the eFTL service, see TIBCO eFTL User’s Guide.
156
| Chapter 9
Monitoring a Realm
Overview
The realm server monitoring interface lets you do these actions:
•
View the server properties and status
•
View a list of clients
•
View individual clients (in greater detail)
•
Disable clients, which prevents them from using FTL transports to
communicate
•
View a list of satellite servers
•
View individual satellite servers (in greater detail)
•
Purge clients or satellites from the realm server’s list
•
View the status of the realm’s current deployment
•
View the status of a deployment as it proceeds
•
View a history of recent deployments
•
Redeploy a previous deployment
•
Delete deployments from the history
•
View the status of groups
•
View the status of transport bridges
•
View the status of store servers and stores
Commands
For command icons available in the monitoring interface, see Table 26, Realm
Server Icons—Monitoring Commands, on page 103.
Monitoring the Realm Server 157
|
Monitoring the Realm Server
The Server page presents a dashboard overview of realm server activity.
158
| Chapter 9
Monitoring a Realm
Table 43 Server Status (Sheet 1 of 2)
Property
Description
Label
The label string of this realm server instance. If you did not supply a label
when starting the realm server (using --server.label) this field
displays the Host:Port value instead.
Host:Port
Location of the realm server (see Connect Port).
Mode
Current state of the realm server. The server can be running (as a
primary), acting as a backup, or running as a satellite.
Started At
Date and time that the server process started.
Current Deployment
Name of the current realm deployment.
(This name originates in the Deploy command.)
Realm Revision
This number increases each time you deploy modified definitions to the
realm server. This number does not change if the changes do not affect
realm semantics (for example, modifying only a description string).
Web API Version
Version of the realm server’s internal API (for features and compatibility).
Server Version
Release number of the realm server executable.
HTTP Port
The realm server listens on this port for initial contact requests from
clients, Python scripts and command line utilities.
After a client initiates a connection, the realm server directs it to interact
at the FTL port.
After a Python script or a command line utility initiates a connection, the
realm server directs it to interact at the GUI port.
FTL Port
Clients interact with the realm server through this port.
GUI Port
The realm server listens on this port for graphical user interface (GUI)
requests from browsers, Python scripts and command line utilities.
Backup Heartbeat
Heartbeat interval between a regular server and its backup.
Backup Timeout
Timeout between a regular server and its backup.
Monitoring the Realm Server 159
|
Table 43 Server Status (Sheet 2 of 2)
Property
Description
Backup To
This realm server process has a backup server at the location indicated
here. During failover, clients can contact the backup server at this location
(hostname and HTTP port).
The value is a link to the backup server’s browser interface.
Backup Status
Status of the backup server and this server’s connection to it. When
connected, this value is a link to the backup server’s home page.
Backup For
This realm server process is a backup server for the regular server at this
location (hostname and HTTP port).
The value is a link to the regular server’s browser interface.
Satellite Heartbeat
Heartbeat interval between primary and satellites.
Satellite Timeout
Timeout between primary and satellites.
Satellite Of
This realm server process is a satellite server of the primary server at this
location (hostname and HTTP port).
The value is a link to the primary server’s browser interface.
Satellite Status
Status of the satellite server and this server’s connection to it. When
connected, this value is a link to the satellite server’s home page.
Clients
Number of clients.
Satellites
Number of satellites.
160
| Chapter 9
Monitoring a Realm
Clients Summary
The Clients summary page lists the clients of the realm server.
Selecting a row (using the check-box at left) holds that row in the display, even if it
would not match the filter.
Table 44 Clients Summary
Column
Description
Client ID
The realm server assigns each client a unique identifier.
Host
The hostname string of the client’s host computer (if available).
Application
Application name (as configured in the realm server).
Instance
Application instance name that the client matches.
Monitoring a Client 161
|
Monitoring a Client
The Client page presents the status and properties of a specific client. It also
presents client monitoring statistics (see Client Statistics on page 163).
162
| Chapter 9
Monitoring a Realm
Table 45 Client Page (Sheet 1 of 2)
Field
Description
ID
Client ID (assigned by the realm server).
Status
•
Running—the client is running, and its local realm definition is up-to-date
(that is, it is the latest realm deployment).
•
Needs Restart—the client is running, but its realm definition is out-of-date,
and it cannot accept a realm deployment. To synchronize the realm
definition, you must restart the process instance.
•
Timed Out—the server has lost the client’s heartbeat signal. Either the client
has stopped, or a network segmentation obstructs the heartbeat signal.
•
Exception—the client is running, but its realm definition is out-of-date. The
deployment caused an error in the client, so the client continues to use its
old realm definition.
Restarting the client might not be sufficient to resolve the issue. For
example, the deployment specifies a new static TCP transport, but the port
is already bound in some other process.
•
Out-of-sync—the client’s realm definition is a different revision than the
server’s.
Last Contact
Time of the most recent contact between the realm server and this client.
Time Since Last
Contact
Approximate elapsed time since the most recent contact between the realm
server and this client.
Application
Name
Application name (as configured in the realm server).
Application
Instance
Application instance name that the client matches.
Realm Revision
Revision number of the realm definition received at the client.
If this number is not equal to the server’s revision, then the client is not
synchronized with the server, and might need to restart.
Client Version
Version string of the client’s FTL library.
Startup Time
Timestamp when the client first contacted the realm server.
FTL User
The client supplied this value for the username property in its realm connect
call.
Monitoring a Client 163
|
Table 45 Client Page (Sheet 2 of 2)
Field
Description
Host Name
Hostname of the client’s host computer.
IP Address
IP address of the client’s host computer.
Identifier
The application identifier of the client. The client passes this string as a
property value when connecting to the realm server.
Other Info
Additional information about the client; for example, hardware, operating
system, process ID.
Notices
Notes about client status, or further explanation of the client’s Status.
Dynamic TCP Transports
When the client uses dynamic TCP transports, the realm server client page
displays the other clients that participate in the mesh using that transport. This
display includes the interfaces where the transport listens for TCP connections.
Client Statistics
When client statistics are available, the realm server client page summarizes them
(displaying mean values over recent samples).
Icons indicate value change direction—up (green up-tick), down (red down-tick),
or unchanged (gray dot).
For complete details, see Chapter 11, Client Monitoring, on page 181.
164
| Chapter 9
Monitoring a Realm
Disabling Clients
Administrators can disable individual client processes; a disabled client cannot
use FTL communications resources.
Consider disabling clients in the following situations:
•
When you modify the realm definition, clients that cannot accept the new
revision might need to restart. If immediately stopping their messages is
critical, you can disable them as a group (and then restart them in some other
way).
•
When you delete (or rename) an application from the realm definition, all
existing client instances of that application implicitly become invalid (that is,
the realm no longer supports them), but they continue running. You must
explicitly disable those clients.
•
If a client consumes more message bandwidth than is appropriate, depriving
other clients of communications resources, consider disabling the
misbehaving client so that other clients can continue to communicate.
•
If a client sends invalid messages that disrupt other clients, disable the
misbehaving client so that other clients can continue to communicate.
Task F Disabling Clients
1. Navigate to the Clients Summary page.
2. Select one or more clients to disable.
3. Click the Disable icon
in the upper-right corner of the page.
4. Optional. Type the reason for disabling. Client programs receive this reason as
a string argument of the realm notification callback.
5. Click OK to confirm.
Task G Purging Clients
When a client process no longer exists, the server purges it from the list of clients
after a timeout interval. You can also explicitly purge clients that list.
1. Navigate to the Clients Summary page.
2. Select one or more clients to purge.
3. Click the Purge icon
Satellites Summary 165
|
Satellites Summary
The Satellites summary page lists the satellites of the realm server. (This list is
empty unless the realm server is a primary server and has actual satellites.)
Table 46 Satellites Summary
Column
Description
Label
This string identifies the satellite server. Clicking this link navigates to the
home page of the satellite server.
Administrators can set a realm server’s label on the command line or in the
configuration file (see --server.label on page 90). If its label is not set, this string
displays the server’s hostname and HTTP port.
Realm Revision
server. This number does not change if the changes do not affect realm
semantics (for example, modifying only a description string).
Status
Aggregated client status of the satellite’s clients; see Status on page 162.
Click this icon to see details of an individual satellite (Satellite Status on
page 166).
166
| Chapter 9
Monitoring a Realm
Task H Purging Satellites
When a satellite server no longer exists, the server purges it from the list of
satellites after a timeout interval. You can also explicitly purge satellites from that
list.
1. Navigate to the Satellites Summary page.
2. Select one or more satellites to purge.
3. Click the Purge icon
Satellite Status
The Satellite Status page presents the details of an individual satellite.
Table 47 Satellite Status (Sheet 1 of 2)
Field
Descriptions
Label
This string identifies the satellite server. For more information see Label on
page 165.
Status
Aggregated client status of the satellite’s clients; see Status on page 162.
Admin UI
A link to the satellite server’s home page.
Last Contact
Time of the last protocol message from the satellite.
Satellites Summary 167
|
Table 47 Satellite Status (Sheet 2 of 2)
Field
Descriptions
Realm
Revision
FTL User
Username supplied when the satellite server started.
Host Name
Hostname of the computer where the satellite server is running.
UUID
Unique ID of the satellite server.
Notices
Log messages related to the satellite server.
server. This number does not change if the changes do not affect realm semantics
(for example, modifying only a description string). If this number is not equal to
the primary’s revision, then the satellite is not synchronized with the primary, and
could require administrator attention.
168
| Chapter 9
Monitoring a Realm
Deployments
The Deployments page presents details about deployments in several panels
(displaying only a subset of those panels at any time):
•
Active Deployment Request, page 170
•
Last Deployment Request, page 173
•
Recent Deployments, page 174
Deployment Information
Table 48 describes information fields that can appear in any of those panels of the
Deployments page.
Table 48 Deployment Information (Sheet 1 of 2)
Field
Description
Name
Name of the deployment.
Description
Administrators can use this text field as a comment to describe the deployment
and attach administrative notes. Optional.
Realm Revision
server. This number does not change if the changes do not affect realm
semantics (for example, modifying only a description string).
Deployed By
Username of the administrator who requested the deployment.
If the realm server enables JAAS authentication, this field displays the
username that requested the deployment.
If JAAS is disabled, this field displays the string anyone.
Deployed On
Deployment request timestamp.
This field displays the date and time that an administrator requested
deployment. (After redeploying, this value can differ from Created On.)
Deployments 169
|
Table 48 Deployment Information (Sheet 2 of 2)
Field
Description
Created By
Username of the administrator who created the deployment package.
If the realm server enables JAAS authentication, this field displays the
username that created the deployment.
If JAAS is disabled, this field displays the string anyone.
Created On
Deployment creation timestamp.
This field displays the date and time that the deployment package was created.
State
This string reports the status and progress of the deployment.
Log
These strings display log output during the deploy transaction.
Changes from
Previous
Deployment
A list of items that have changed since the previous deployment.
+
The item is added in this deployment.
-
The item is deleted in this deployment.
~
The item has changed in this deployment.
170
| Chapter 9
Monitoring a Realm
Active Deployment Request
When a deployment requires administrator intervention, the Deployments page
displays the Active Deployment Request panel (at its top). This panel presents the
state of the deploy command in progress, and prompts the administrator to select
an action in response to problems at clients or satellites.
Active Deployment Request 171
|
Table 49 Active Deployment Request
Field
Description
These sections can appear in the Active Deployment Request panel. Sections appear in the display
only when they contribute relevant information (otherwise they are hidden).
Numbers indicate the phases of the deployment:
1. The server is expecting deployment test responses from clients and
satellites.
2. The server is waiting for the administrator to Proceed or Cancel the
deployment. (If the phase 2 timeout expires, the server automatically
cancels the deployment.)
3. The server is either proceeding or cancelling.
Deployment
Identification
This section identifies the deployment by Name, Description, Created By and
Created On (for descriptions of these items, see Table 48 on page 168).
Phase Time Left
This row indicates the time remaining before phase 2 timeout.
Response
Summary
This section displays a graphic that summarizes the deployment test responses.
The first column summarizes responses from direct clients of the realm server;
the second column summaries responses from satellites of the realm server.
The fraction in the center indicates the number of responses the server has
already received over the number of responses the server expects. An outer
ring reflects this fraction graphically.
The color of the outer ring and the text label within the ring both indicate the
consolidated response so far.
Response Lists
A list of client and satellite IDs that are still Expected (that is, have not yet
responded), Need Restart, or reported an Exception. After phase timeout, the
Expected list becomes a Did Not Respond list.
Ellipses (...) at the bottom indicates that the display has truncated a long list.
Notices
The server displays additional information that might affect your decision.
Available
Actions
To continue the deployment, click the Proceed button.
See Also
To stop the deployment, click the Cancel button.
172
| Chapter 9
Monitoring a Realm
New Clients during a Deployment
When a deployment problem requires administrator intervention, the realm
server does not send the realm definition to new clients.
You must first resolve the problem by clicking one of the available actions. Your
choice determines the official realm definition (either the new deployment or the
previous deployment). Then the realm server can send that realm definition in
response to requests from new clients.
Last Deployment Request 173
|
Last Deployment Request
The Last Deployment Request panel presents detailed information about the most
recent realm deployment request—whether or not that deployment succeeded.
For an explanation of these items, see Deployment Information on page 168.
When a deployment is in progress, this section is replaced by the section Active
Deployment Request on page 170.
174
| Chapter 9
Monitoring a Realm
Recent Deployments
The Recent Deployments panel lists deployment requests.
Table 50 Recent Deployments
Column
Description
Name
Deployed By
Deployed On
Created On
For descriptions of these items, see Table 48 on page 168.
View.
Click this icon to view details of this deployment request; see Deployment
Information on page 168.
Redeploy.
Click this icon to redeploy this deployment package.
Delete.
Click this icon to delete a deployment package from the list.
Redeploy
The Redeploy icon appears only when it is permissible to change the
deployment—that is, to return to an earlier realm definition. Usually, only the
primary realm server has permission to change the deployment. However, if the
primary is unavailable, administrators can change the redeploy through a backup
or satellite server.
Recent Deployments 175
|
For example, consider a situation in which hardware or network failure prevents
deployment from completing. The primary server stores the new deployment,
pushes it to its clients, and affiliated realm servers. Before the backup and satellite
servers can completely store the deployment, failure disconnects the primary
from its clients, which failover to the backup realm server. Those clients already
have the new deployment, but the backup and satellite server do not; clients of
satellites have the previous deployment. Using the backup server’s GUI, the
administrator can redeploy the previous realm definition to all clients, and so
ensure that all clients use a common realm definition.
176
| Chapter 9
Monitoring a Realm
| 177
Chapter 10
Configuring a Realm using Python Scripts
This chapter presents a Python script interface that lets you define and configure a
realm.
(For a browser-based graphical configuration interface, see Chapter 7,
Configuring a Realm using the GUI, on page 121.)
Topics
•
Overview, page 178
•
Using the Realm Server Python Script, page 179
178
| Chapter 10
Overview
Python scripts give administrators command line access to realm servers and
realm definitions.
Table 51 Realm Server Python Scripts and Related Files
Filename (Location)
Description
rs_script.py
This Python script lets you add and delete definitions in a realm.
(bin directory)
It can read a realm definition from either a JSON file or a realm
server process. It can write a modified realm definition to either a
JSON file or a realm server process.
When writing to a realm server, this script can also instruct the
server to deploy the modified realm definition.
The script can read a command file that specifies actions to
modify the realm definition.
rs_scriptlib.py
rs_python2utils.py
These Python libraries define functions used by rs_script.py
and other Python scripts.
rs_python3utils.py
(bin directory)
rs_script_sample_input.txt
(samples directory)
This command file for rs_script.py specifies actions that
define the sample realm.
Using the Realm Server Python Script 179
|
Using the Realm Server Python Script
Before using rs_script.py, you must first ensure that Python (version 2.4 or
later) is installed.
The script’s help option (rs_script.py -h) outputs detailed information about
its options and commands—including command line examples.
You can also use the sample command file (rs_script_sample_input.txt) as a
model for composing your own command files.
180
| Chapter 10
| 181
Chapter 11
Client Monitoring
This chapter presents client monitoring and statistics.
Topics
•
Overview, page 182
•
Storage, page 183
•
Catalog of Client Statistics, page 184
•
Web API, page 187
182
| Chapter 11
Client Monitoring
Overview
The FTL client library monitors each client process, sampling several values that
reveal operating behavior and performance. The client library sends these value
samples to the realm server, which stores them, and displays them for
administrators. A realm server web API also makes these samples available for
visual analysis programs and for longer-term storage.
Sampling
Every client process—throughout the realm—collects sample data at the same
interval. The realm property Client Monitoring Sample Interval determines
that interval. Zero is a special value, instructing all clients to disable the
monitoring feature.
Each client sends all its pending samples to the realm server in the next heartbeat
message. If the heartbeat interval is large, then the realm server receives a batch of
accumulated samples after a delay (that is, at the next heartbeat). The first batch of
data becomes available with the first heartbeat after the first sample interval.
Display
For each client, the realm server displays a summary of recent sample data (see
Client Statistics on page 163).
You can use third-party statistical analysis tools or visualization tools to examine
sample data in greater depth.
Storage 183
|
Storage
The realm server maintains a recent subset of samples from each client. To use
memory resources efficiently, the realm server discards older samples to make
room for new sample data.
In this sense, the realm server is a temporary store for sample data. We
recommend that you arrange to periodically download sample data from the
server (using the realm server web API), and copy it to long-term storage.
Estimating Maximum Memory Size
You can estimate the realm server’s maximum memory requirements to store
client monitoring data at approximately 70 kilobytes per counter.
The number of counters depends on the number of application processes, and on
the number of endpoints, transports and event queues in each application
process; see Table 52.
Table 52 Client Monitoring Resource Usage
1 counter per client process
2 counters per endpoint
2 counters per event queue
3 counters per transport (for all transport types, but see below for multicast)
9 counters per multicast transport (6 specific to multicast, in addition to the 3
for all transports)
Task I
Calculating Maximum Memory to Store Client Monitoring Data
1. For each application instance definition, determine the number of counters
per client process of that application instance. Combine information from the
application instance definitions with information from Table 52).
2. For each application instance definition, multiply its counters per client
process (previous step) by the expected number of process instances.
3. Sum that number of counters over all the application instance definitions.
4. Multiply by 70 kilobytes to yield the total memory requirements for the realm
server to store all client monitoring data.
184
| Chapter 11
Client Monitoring
Catalog of Client Statistics
Standard Client Statistics
Table 53 Client Statistics (Sheet 1 of 2)
Statistic Type
Descriptions
Tracking
Queue Discards
For each event queue in the client process, a counter of this
type tracks the number of inbound messages that the queue
discarded.
Per queue
For each event queue in the client process, a counter of this
type reports the maximum number of messages in the
queue during the sample interval.
Per queue
For each transport in the client process, a counter of this
type tracks the outbound data bytes on the transport.
Per transport
type tracks the inbound data bytes on the transport.
Per transport
type tracks the data loss (inbound loss events) on the
transport. It is not possible to measure the magnitude of the
events in bytes.
Per transport
For each client process, a single counter of this type reports
the number of distinct dynamic formats that the client
creates within the sample interval. (This number includes
message formats used in recent intervals; the number can
decrease as the client library automatically discontinues
unused formats.)
Per client
For each endpoint in the client application, a counter of this
type tracks the outbound data messages through the
endpoint.
Per endpoint
For each endpoint in the client process, a counter of this type
tracks the inbound data messages through the endpoint.
Per endpoint
Queue Backlog
Bytes Sent
Bytes Received
Data Lost
Dynamic Formats
Messages Sent
Messages Received
Cumulative
Instantaneous
Cumulative
Cumulative
Cumulative
Instantaneous
Cumulative
Cumulative
Catalog of Client Statistics 185
|
Table 53 Client Statistics (Sheet 2 of 2)
Statistic Type
Descriptions
Tracking
Store Mismatch
Messages
Store mismatch is a misconfiguration in which a direct path
transport connects two endpoints that are associated with
two different persistence stores.
Per endpoint
Cumulative
For each endpoint in the client process, a counter of this type
detects message flows that result from store mismatch. Any
non-zero value indicates a store mismatch misconfiguration.
Bytes sent and received need not correlate exactly with messages sent and
received on corresponding endpoints (for example, filtering and optimizations
can decouple these statistics).
Client Statistics for Multicast Transports
FTL gathers additional statistics for each multicast transport.
For all statistics in Table 54, tracking is per multicast transport, and cumulative
since transport creation.
Table 54 Client Statistics for Multicast Transports (Sheet 1 of 2)
Statistic Type
Description
Packets Sent
For each multicast transport in the client process, a counter of this type tracks
the outbound data packets on the transport.
This counter includes all outbound data packets (including original data
packets and retransmitted data packets).
Packets Received
the inbound data packets on the transport.
This counter includes all inbound data packets (including original data
packets and retransmitted data packets).
Packets
Retransmitted
outbound retransmission (packets retransmitted) on the transport.
If the transport retransmits a packet several times, it increments this counter
each time.
Packets Missed
retransmit requests (packets requested) for missed inbound packets on the
transport.
186
| Chapter 11
Client Monitoring
Table 54 Client Statistics for Multicast Transports (Sheet 2 of 2)
Statistic Type
Description
Packets Lost
Outbound
outbound dataloss (packets discarded) on the transport.
Packets Lost
Inbound
inbound dataloss (packets accounted lost) on the transport.
The transport accounts a packet as lost after its reliability constraints expire.
Store Server Statistics
See Persistence Server Statistics on page 288.
Web API 187
|
Web API
The client monitor web API consists of a single command, with one optional
parameter. This command queries the realm server for accumulated client
statistics:
http://realm_server_host:gui_port/cmd/monitor?start_after=sample_number
Table 55 Monitor API: Monitor Command, Parameters
Parameter
Description
realm_server_host:gui_port
Location of the realm server (see Interface Port on page 87).
start_after=sample_number
Optional.
When present, limit the response to items with sample strictly
greater than sample_number.
-1 is a special value, which requests all samples that the realm
server currently retains in its store.
When absent, the default value is -1.
The monitor command returns a response in JSON format. The response contains
of an array of clients; for each client, an array of statistics (in the series field);
and for each statistic, an array of samples (in the data field). For details, see tables
56–59.
Table 56 Monitor API: Response
Field
Description
clients
An array of client elements, each presenting the statistics for a single client
process; see Table 57
status
Query return status.
version
Realm server version.
188
| Chapter 11
Client Monitoring
Table 57 Monitor API: Client Element
Field
Description
connect_time
Time (in milliseconds since the epoch) at which the client connected to the realm
server.
id
Unique client ID number (assigned by the realm server).
series
An array of series elements, each presenting recent samples for a single statistic;
see Table 58.
Table 58 Monitor API: Series Element
Field
Description
context
Name of the object that this statistic monitors (for example, the name of an
endpoint, event queue, transport or application).
data
An array of data elements; see Table 59.
description
Name of the statistic type (mixed case string containing spaces).
type
Name of the statistic type (lower case string with underscores, and without
whitespace).
Table 59 Monitor API: Data Elements
Field
Description
sample
Sample number.
The sample number is a unique label for all the data values that a specific client
collects during a specific sample interval.
up_time
Time (in milliseconds) from the client’s initial connection to the realm server (see
connect_time) until it closed the sample interval.
value
Value of the statistic at the sample interval.
All values are 64-bit integers.
Web API 189
|
Example 2 Client Monitor Response from the Realm Server
{
"clients":[
{
"connect_time":1334693445686,
"id":71041,
"series":[
{
"context":"tibsend-endpoint",
"data":[
{
"sample":5,
"up_time":180010,
"value":179
}],
"description":"Messages Sent",
"type":"messages_sent"
},
{
"context":"shm-sendrecv-tport",
"data":[
{
"sample":5,
"up_time":180010,
"value":229
}],
"description":"Bytes Sent",
"type":"bytes_sent"
}]
}],
"status":"OK",
"version":"2.1"
}
190
| Chapter 11
Client Monitoring
| 191
Chapter 12
Rendezvous Adapter
This chapter describes a message adapter that can connect TIBCO FTL
applications with TIBCO Rendezvous® applications.
Readers of this chapter must already understand TIBCO Rendezvous messaging
technology.
Topics
•
Adapter Overview, page 192
•
Adapter Operation, page 194
•
Using tibrvadapter, page 196
•
Adapter Configuration, page 198
•
Adapter Administration—Realm, page 204
•
Adapter Subject Translation, page 205
•
Adapter Datatype Mapping, page 206
•
Request/Reply Interactions through the Adapter, page 209
•
Rendezvous Subjects, page 212
•
Restrictions, page 214
192
| Chapter 12
Rendezvous Adapter
Adapter Overview
The TIBCO Rendezvous adapter converts messages so FTL programs can
communicate with existing Rendezvous programs. The adapter translates
messages in both directions.
To understand the adapter, consider it from three perspectives:
•
FTL
•
Rendezvous
•
Adapter
Figure 15 Rendezvous Adapter
RV Client
Program
Client Connection
Rendezvous Adapter
FTL Transport
RV to FTL Translator
FTL
Program
RV
FTL
FTL
Program
FTL to RV Translator
RV Client
Program
FTL
Program
FTL
From the perspective of FTL applications (right side of Figure 15), the adapter
behaves like any other FTL application. It can publish messages and subscribe to
messages. It contacts the realm server to get formats and transports, just as any
other FTL application would. It communicates with other FTL applications over
FTL transports, as defined in the realm.
Rendezvous
From the perspective of Rendezvous applications (left side of Figure 15), the
adapter appears like a Rendezvous daemon—but its operation differs
significantly.
Adapter Overview 193
|
Rendezvous applications connect to the adapter as they would connect to a
daemon. The adapter delivers inbound messages to applications, and accepts
outbound messages from applications (as a daemon would). Furthermore, all the
clients that connect to the same Rendezvous adapter process can exchange
Rendezvous messages—just as if they were connected to the same daemon.
However, unlike a daemon, the adapter is not connected to any Rendezvous network.
The adapter neither transmits outbound Rendezvous messages on a network, nor
receives inbound Rendezvous messages from a network. On its Rendezvous side,
it communicates only with the clients that connect to it. (That is, it does not
communicate with other Rendezvous programs on the network that are not
themselves clients of the adapter.)
Adapter
Within the adapter itself, messages flow in two directions between its
Rendezvous side and its FTL side. FTL messages and Rendezvous messages are
very different, so the adapter translates these messages according to its
configuration.
The central portion of the adapter in Figure 15 on page 192 shows the two
translators, one for each direction.
194
| Chapter 12
Rendezvous Adapter
Adapter Operation
The adapter has three operating parts:
•
Start Phase
•
FTL Side
•
Rendezvous Side
Start Phase
1. The adapter start phase begins by reading the configuration file.
2. The adapter contacts the realm server to get the realm definition.
3. The adapter validates its configuration.
If the adapter configuration is incompatible with the realm in any way, or
violates other constraints, the adapter outputs an error and exits.
4. If the start phase succeeds in reaching this point, the adapter starts both its
FTL side and its Rendezvous side.
FTL Side
The FTL side creates one FTL subscriber for each endpoint in the adapter
configuration. These subscribers do not include content matchers; they receive all
messages on the endpoint.
Each time an FTL subscriber receives a message with a format specified in one of
the configuration’s from-FTL tags, the adapter attempts to translate it to a
Rendezvous message. The from-FTL tag guides the translation. The adapter first
finds the set of FTL fields that translate into the Rendezvous subject or inbox
name. Then the adapter translates each remaining field:
•
The FTL field name becomes a Rendezvous field name.
•
Every FTL field datatype either maps unambiguously to a Rendezvous field
datatype, or raises an error (for details, see Adapter Datatype Mapping,
page 206).
•
The FTL field value translates to the Rendezvous field value (of the
appropriate datatype).
After translating all the fields, the adapter transmits the translated Rendezvous
message to all its clients that have expressed interest in the translated Rendezvous
subject.
Adapter Operation 195
|
Rendezvous Side
The Rendezvous side begins by listening for connections from Rendezvous
clients. Clients connect to the adapter as they would connect to a Rendezvous
daemon.
The adapter processes each message that its Rendezvous clients send.
Each time a Rendezvous message matches the subject specification in one of the
configuration’s from-RV tags, the adapter attempts to translate it to an FTL
message. The from-RV tag guides the translation.
1. The adapter translates and stores the Rendezvous subject.
— If the Rendezvous subject is a multicast subject name, the adapter stores its
elements in FTL fields.
— If the Rendezvous subject is an inbox, the adapter maps it to an FTL inbox,
and stores the FTL inbox in an FTL field.
2. Then the adapter attempts to fill each of the remaining fields of the FTL
format with values from the Rendezvous message.
The adapter attempts to get a Rendezvous field with the same name as the
FTL field.
— If the Rendezvous field type maps to an FTL field datatype (see Adapter
Datatype Mapping, page 206), then the adapter translates the Rendezvous
field value to an FTL field value (of the appropriate datatype).
— If the Rendezvous field type does not map to an FTL field datatype (see
Adapter Datatype Mapping, page 206), then the adapter either discards the
entire message, or skips the field—depending on the discard-messages
attribute of the from-RV tag.
3. After translating all the FTL fields, the adapter publishes the translated FTL
message on the relevant FTL endpoints.
Rendezvous Unnamed Fields
Rendezvous messages support unnamed fields, accessed only by index or field
identifier. In contrast, FTL does not support unnamed fields.
The adapter does not translate unnamed fields. When translating a Rendezvous
message, the adapter ignores unnamed fields.
196
| Chapter 12
Rendezvous Adapter
Using tibrvadapter
Administrators use tibrvadapter (the adapter executable) to start the adapter
process.
The command line parser accepts either form.
Table 60 tibrvadapter
Short
Long
Parameters
Description
-c
--config
path
Required.
The Rendezvous adapter reads its
-pf
--password-file
path
Optional. (Required for JAAS
authentication.)
When present, the Rendezvous adapter
reads a username and password from the
file at path, and authenticates itself to the
realm server using those credentials. For
details, see Password File on page 83.
-rs
--realmserver
URL
Optional.
When present, the Rendezvous adapter
connects to the realm server at URL
(overriding the URL in the configuration
file).
-s
--secondary-realm-server
URL
Optional.
When present, the Rendezvous adapter can
connect to the backup realm server at URL
(overriding the secondary-URL in the
configuration file).
-h
--help
Display a help message describing the
command line parameters and options.
Using tibrvadapter 197
|
Password File
configure credentials for the Rendezvous adapter.
The adapter process authenticates itself using credentials that it reads from an
ASCII password file (see --password-file on page 196).
Disabled
If an administrator disables an adapter process (using the realm server
monitoring interface), the adapter does not restart itself. You must restart it—
either manually, or through some automatic mechanism of the operating system
(for example, register it as an auto-start service).
198
| Chapter 12
Rendezvous Adapter
Adapter Configuration
The adapter configuration file is an XML document. This section presents the
XML tags and their meanings.
All attribute values must be strings, delimited by double-quote characters.
Table 61 Configuration Language for Rendezvous Adapter (Sheet 1 of 6)
XML Tag
Description
Top Level Tag
realm
Begin the adapter configuration. Exactly one.
•
URL
Required. The adapter contacts the realm server at this location. A
realm server must be listening at that location.
•
secondary-URL
Optional. If the regular realm server fails, the adapter can failover
to the backup realm server at this location.
•
application-name
Required. The adapter uses this name to get its tailored realm from
the realm server. The realm must define an application with this
name.
Contains: log (at most one), RV-clients (exactly one), service (at
least one), from-FTL (zero or more).
Adapter Configuration 199
|
XML Tag
Description
Rendezvous Parameters
RV-clients
Configure parameters that affect the adapter’s behavior with respect to
its clients. Exactly one.
The adapter accepts the following attributes:
•
listen
Optional. When present, the adapter listens on this TCP port for
connection requests from Rendezvous client programs.
When listen is absent, the adapter listens for Rendezvous client
connections on port 7900.
•
max-consumer-buffer
Optional. When present, the adapter enforces this upper bound (in
bytes) on each consumer buffer (the outbound queue of translated
messages for a client transport). When the adapter produces
translated messages faster than the client consumes them, the
buffer overflows this size limit, and the adapter discards the oldest
messages to make space for new messages. The client transport
receives a CLIENT.SLOWCONSUMER advisory.
When absent or zero, the adapter does not enforce a size limit on
the consumer buffer. (However, a 60-second time limit on messages
still limits buffer growth, independently of this parameter.)
200
| Chapter 12
Rendezvous Adapter
XML Tag
Description
Service
service
Configure a Rendezvous service, and adapter behavior with respect to
that service. At least one.
•
port
Required. The adapter maps this Rendezvous service to one or
more FTL endpoints, translating messages in both directions.
Contains: endpoint (at least one), from-RV (zero or more).
endpoint
At least one.
•
name
Required. The adapter maps this FTL endpoint to a Rendezvous
service (see the enclosing service tag), translating messages in
both directions.
When several endpoints are present, the adapter translates each
Rendezvous message from the service only once, and forwards the
translation to all of the endpoints.
|
XML Tag
Description
Translating Rendezvous to FTL
from-RV
Configure a translation from Rendezvous to FTL. Zero or more.
•
subject
Required. The adapter selects a subset of Rendezvous messages to
translate from the service. That is, the adapter translates only
messages with subjects that match this specification (which may
contain Rendezvous wildcard elements).
For important details, see Rendezvous Subjects on page 212.
•
format
Required. The adapter translates Rendezvous messages into this
managed FTL format.
•
parse-subject
Required. This string instructs the adapter as it parses the
Rendezvous message subject into fields in the target FTL format.
For the syntax and semantics of this string, see Parsing a
Rendezvous Subject to FTL Fields, page 205.
•
discard-messages
Optional. This value governs adapter behavior when it cannot
translate a Rendezvous field into an FTL field type.
When true, the adapter discards the entire Rendezvous message,
and does not produce an FTL translation.
When false, the adapter skips the offending field, and continues
its attempt to translate the rest of the message to FTL.
When absent, the default is false.
•
reply-field
Required for request/reply. Specifies a field name in the FTL
format. If the Rendezvous message includes a reply subject, the
adapter maps that Rendezvous inbox name to an FTL inbox, and
stores the FTL inbox in this FTL field. (Later, when an FTL program
sends a reply to that FTL inbox, the adapter translates the reply and
forwards the translation to the original Rendezvous inbox subject.)
202
| Chapter 12
Rendezvous Adapter
XML Tag
Description
Translating FTL to Rendezvous
from-FTL
Configure a translation from FTL to Rendezvous. Zero or more.
•
format
Required. Specifies a managed FTL format. The adapter uses
information in this tag to translate all FTL messages with this
format.
•
assemble-subject
Required. This string instructs the adapter as it assembles
designated fields of an FTL message into a Rendezvous subject
name. For the syntax and semantics of this string, see Assembling
FTL Fields to a Rendezvous Subject, page 205.
•
reply-field
Required for request/reply. Specifies a field name in the FTL
format. When present, the adapter maps the inbox value of this
FTL field to a Rendezvous inbox reply subject, which it stores on
the Rendezvous message. (Later, when a Rendezvous program
sends a reply to that reply subject inbox, the adapter translates the
reply and forwards the translation to the original FTL inbox.)
•
expect-reply-format
Required for request/reply. Specifies an FTL format. When present,
the adapter remembers that the FTL requestor expects a reply
message with this format, and uses this format when translating
the reply.
•
discard-messages
Optional. This value governs adapter behavior when it cannot
translate an FTL field into a Rendezvous field type, and also when
it cannot translate a Rendezvous field in a reply message into an
FTL field type.
When true, the adapter discards the entire message, and does not
produce a translation.
When false, the adapter skips the offending field, and continues
its attempt to translate the rest of the message.
When absent, the default is false.
|
XML Tag
Description
Logging
log
Configure logging behavior. At most one.
•
level
Optional. This string determines the categories of errors that the
adapter logs. When absent, the default log level is info.
For more information about log level semantics, see Log Levels in
TIBCO FTL Development.
204
| Chapter 12
Rendezvous Adapter
Adapter Administration—Realm
The realm definition must satisfy all of these constraints to support the FTL side of
the adapter.
Communication through Transports
Administrators must configure transports to establish a bus to carry messages
between FTL programs and the FTL side of the adapter. The realm must configure
appropriate communications paths for each message stream.
Bidirectionality
During its start phase, the adapter creates a publisher and a subscriber for each of
its FTL endpoints. Administrators must ensure that the realm supports these
objects for each adapter endpoint. That is, for each adapter endpoint, the
connectors (in the adapter’s application instance definition) must cover (at least)
the send ability and the receive ability (even if you intend that messages flow
through the adapter in only one direction).
One-to-One Abilities
If the adapter uses an endpoint to forward one-to-one messages, then the
connectors (in the adapter’s application instance definition) that implement that
endpoint must cover either the send inbox ability, the receive inbox ability, or
both—as needed.
(In contrast, if the adapter does not forward one-to-one messages, then the
connectors need not cover either of these abilities.)
Adapter Subject Translation 205
|
Adapter Subject Translation
This section describes the translation between Rendezvous subjects and
designated FTL fields.
Parsing a Rendezvous Subject to FTL Fields
The parse-subject attribute of the from-RV configuration tag instructs the
adapter as it parses the Rendezvous message subject into fields in the target FTL
format.
•
Each element of this string has the form #n=field_name, where n represents the
subject element position in the Rendezvous subject, and field_name designates a
field in the target FTL format.
•
The comma (,) character separates the elements.
The adapter stores each subject element as the value of the corresponding FTL
field. The datatype of all of these fields must be TIB_FIELD_TYPE_STRING.
If the Rendezvous subject name has fewer elements than the parser requires, the
adapter discards the message immediately.
Assembling FTL Fields to a Rendezvous Subject
The assemble-subject attribute of the from-FTL configuration tag instructs the
adapter as it assembles designated fields of an FTL message into a Rendezvous
subject name.
•
Each element of this string has the form %field_name, where field_name designates
a field in the FTL format.
•
The dot (.) character separates the elements.
The adapter assembles a Rendezvous subject by concatenating the values of the
FTL fields, separating them with dots.
206
| Chapter 12
Rendezvous Adapter
Adapter Datatype Mapping
This section presents the details of adapter datatype mapping between FTL
messages and Rendezvous messages.
FTL to Rendezvous
The mapping from FTL message fields to Rendezvous message fields is
straightforward. Each FTL type maps to a Rendezvous type, according to
Table 62; the mapping is intuitive, and requires no conversion. Some FTL types do
not map to any Rendezvous representation; these fields raise an error (see Error
on page 208).
Table 62 Datatype Mapping: FTL to Rendezvous
FTL Type
Rendezvous Type
TIBRVMSG_OPAQUE
TIB_FIELD_TYPE_LONG
TIBRVMSG_I64
TIBRVMSG_I64ARRAY
TIBRVMSG_F64
TIBRVMSG_F64ARRAY
TIBRVMSG_STRING
TIBRVMSG_STRINGARRAY
TIB_FIELD_TYPE_MESSAGE
Error
TIB_FIELD_TYPE_MESSAGE_ARRAY
Error
TIB_FIELD_TYPE_INBOX
Error
TIBRVMSG_DATETIME
TIB_FIELD_TYPE_DATETIME_ARRAY
Error
Adapter Datatype Mapping 207
|
Rendezvous to FTL
Because Rendezvous supports a very rich set of datatypes, while FTL supports a
deliberately narrow set of datatypes, the mapping from Rendezvous message
fields to FTL message fields is more complicated. The adapter coerces several
Rendezvous types into the same FTL type. Some Rendezvous types do not map to
any FTL representation; these fields raise an error (see Error on page 208).
Table 63 Datatype Mapping: Rendezvous to FTL (Sheet 1 of 2)
Rendezvous Type
FTL Type
TIBRVMSG_OPAQUE
TIBRVMSG_BOOL
Error
TIBRVMSG_I8
TIB_FIELD_TYPE_LONG
TIBRVMSG_I16
TIBRVMSG_I32
TIBRVMSG_I64
TIBRVMSG_U8
TIBRVMSG_U16
TIBRVMSG_U32
TIBRVMSG_U64
Error
TIBRVMSG_I8ARRAY
TIBRVMSG_I16ARRAY
TIBRVMSG_I32ARRAY
TIBRVMSG_I64ARRAY
TIBRVMSG_U8ARRAY
TIBRVMSG_U16ARRAY
TIBRVMSG_U32ARRAY
TIBRVMSG_U64ARRAY
Error
TIBRVMSG_F32
TIBRVMSG_F64
TIBRVMSG_F32ARRAY
TIBRVMSG_F64ARRAY
TIBRVMSG_STRING
TIBRVMSG_STRINGARRAY
TIBRVMSG_MSG
Error
208
| Chapter 12
Rendezvous Adapter
Table 63 Datatype Mapping: Rendezvous to FTL (Sheet 2 of 2)
Rendezvous Type
FTL Type
TIBRVMSG_MSGARRAY
Error
TIBRVMSG_DATETIME
All other Rendezvous types
Error
Error
When a datatype mapping raises an error, the adapter responds according to the
discard-messages attribute (in the from-RV or from-FTL tag). If the value of
discard-messages is true, then the adapter discards the entire message.
Otherwise, the adapter skips the offending field and continues translating the
message.
Request/Reply Interactions through the Adapter 209
|
Request/Reply Interactions through the Adapter
Request/reply interactions involve complex configuration constraints. This
section presents the three possible situations (these three are the only possible
situations).
Primary FTL Request, Secondary Rendezvous Reply to an Inbox
An FTL program sends a request message. The adapter detects that it is a request
message because it meets all of these criteria:
•
The format of the message matches the format of a from-FTL configuration
tag.
•
The reply-field of that from-FTL tag specifies the name of an FTL field—
which we call the reply field.
•
The realm defines the format such that the reply field has type
TIB_FIELD_TYPE_INBOX.
•
That reply field is present in the message.
•
The expect-reply-format of the from-FTL tag specifies the name of an FTL
format—which we call the reply format. The requestor expects a reply message
in this reply format. (The realm must define the reply format.)
The adapter arranges a mechanism through which a Rendezvous program can
reply to the FTL request.
1. The adapter gets the value of the reply field—namely, the FTL inbox where
the requestor awaits a reply.
2. The adapter maps that FTL inbox to a Rendezvous inbox (within the adapter).
3. In the Rendezvous translation of the request message, the adapter sets the
reply subject to that Rendezvous inbox.
4. Later, when a Rendezvous program sends a reply to that inbox, the adapter
receives it, translates it to an FTL message using the reply format, and
forwards it to the FTL inbox where the requestor awaits the reply.
To configure this case, ensure that the adapter configuration meets the five criteria
in the above bullets.
210
| Chapter 12
Rendezvous Adapter
Secondary Rendezvous Request to an Inbox, Tertiary FTL Reply
The Rendezvous reply (in the previous case) could itself be a secondary request in
a longer chain of point-to-point messages. The adapter detects this situation
because the secondary message meets all of these criteria:
•
The adapter receives the secondary message at an adapter inbox, so the
message must be a Rendezvous reply to an FTL request.
•
The reply subject of the secondary Rendezvous message contains a
Rendezvous inbox name, so the sender must be awaiting a tertiary reply.
Rendezvous Adapter
RV Client
Program
FTL
Program
2a A Rendezvous
client receives
the primary
request, and
sends a reply
that is itself a
secondary
request.
2b The adapter
translates the
secondary
request, and sets
the reply field.
1b The adapter
translates the
primary request,
and sets the
reply subject.
3b The adapter
translates the
tertiary reply.
1a An FTL program
sends a primary
request.
3a An FTL program
receives the
secondary
request, and
sends a tertiary
reply.
The adapter repurposes part of the existing mechanism (from the primary
request) so an FTL program can send a tertiary reply to the secondary
Rendezvous request. The part it repurposes is the reply field—an FTL field name,
specified as the value of the reply-field of the from-FTL configuration tag (the
same tag that governed translation of the primary FTL request message).
1. The adapter gets the reply subject—namely, the Rendezvous inbox name
where the requestor awaits a reply.
2. The adapter maps that Rendezvous inbox to an FTL inbox (within the
adapter)—which we call the reply inbox.
3. In the FTL translation of the secondary request message, the adapter stores the
reply inbox in the reply field.
Request/Reply Interactions through the Adapter 211
|
4. Later, when an FTL program sends its tertiary reply to the reply inbox, the
adapter receives it, translates it to a Rendezvous message, and forwards it to
the reply subject (that is, the Rendezvous inbox where the secondary
requestor awaits the tertiary reply).
Because you have already configured the adapter to translate the primary request
(see Primary FTL Request, Secondary Rendezvous Reply to an Inbox, page 209),
you do not need any additional configuration to forward the secondary request,
nor to forward the tertiary reply.
Nonetheless, if the format of the tertiary reply differs from the format of the
primary request, you must configure a separate from-FTL tag to translate that
format. (This case has the same form as the configuration for the primary request.)
Primary Rendezvous Request to a Subject, Secondary FTL Reply to an Inbox
A Rendezvous program sends a request message to a multicast subject (not to an
inbox). The adapter detects that it is a multicast request message because it meets
all of these criteria:
•
The subject of the message matches the subject attribute of a from-RV
configuration tag.
•
The reply-field attribute of that from-RV tag specifies the name of an FTL
field—which we call the reply field.
•
The realm defines the format such that the reply field has type
TIB_FIELD_TYPE_INBOX.
The adapter arranges a mechanism through which an FTL program can reply to
the Rendezvous request.
1. The adapter gets the reply subject—namely, the Rendezvous inbox name
where the requestor awaits a reply.
2. The adapter maps that Rendezvous inbox to an FTL inbox (within the
adapter)—which we call the reply inbox.
3. In the FTL translation of the request message, the adapter stores the reply
inbox in the reply field.
4. Later, when an FTL program sends a reply to that reply inbox, the adapter
receives it, translates it to a Rendezvous message, and forwards it to the reply
subject (that is, the Rendezvous inbox where the requestor awaits the reply).
To configure this case, ensure that the adapter configuration meets the three
criteria in the above bullets.
212
| Chapter 12
Rendezvous Adapter
Rendezvous Subjects
The adapter carefully validates the subject attribute of each from-RV tag, using
the following rules:
•
Within the scope of a service tag, the subjects of the from-RV tags must not
collide with one another. (This restriction does not apply between from-RV
tags that are in different service tags.)
•
If a literal subject is identical to a previous literal subject, then they collide (not
permitted).
•
If a literal subject matches a previous wildcard subject, then they do not
collide (permitted).
•
If a wildcard subject matches a previous literal subject, then they do not
collide (permitted).
•
If a wildcard subject matches a previous wildcard subject, then they collide
(not permitted).
Examples
Table 64 Validating Rendezvous Subjects
Subject 1
Subject 2
Conformance
a.b
a.b.c
Permitted
a.b
a.*
Permitted
a.*
a.b
Permitted
a.b
a.>
Permitted
a.>
a.b
Permitted
a.b
a.b
Collide
a.*
a.>
Collide
a.>
a.*
Collide
a.*
*.b
Collide
*.b
a.*
Collide
Rendezvous Subjects 213
|
Messages that Match Two Rendezvous Subjects
The above restriction against colliding subjects helps ensure that the adapter
translates each Rendezvous message at most once.
The adapter forbids combinations in which two wildcard subjects collide,
preventing ambiguity.
The adapter permits combinations in which a message might match both a literal
subject and a wildcard subject. In this situation, the adapter translates the
message according to the from-RV tag that specified the literal subject.
214
| Chapter 12
Rendezvous Adapter
Restrictions
•
The adapter does not support dynamic formats. It can translate an FTL
message only if it uses a pre-loaded format. It can translate a Rendezvous
message only into a managed FTL format.
•
The adapter does not translate FTL messages of types
TIB_BUILTIN_MSG_FMT_OPAQUE (nor TIB_BUILTIN_MSG_FMT_KEYED_OPAQUE).
Instead, define a managed format with one opaque field.
| 215
Chapter 13
Groups of Applications
Applications can use the group facility to coordinate fault-tolerant operation, or to
distribute operating roles among application processes. This chapter presents the
group facility for administrators.
Before reading this chapter, we recommend that you first read the corresponding
chapter in TIBCO FTL Development.
Topics
•
Administrative Overview, page 216
•
Using the Group Setup Script, page 218
•
Group Server Monitoring Page, page 220
216
| Chapter 13
Administrative Overview
A set of application processes can join a group. Each member of a group receives
an ordinal—that is, a number representing its current position within the group.
Application program logic uses the ordinal to select one of several possible
operating roles. A group server tracks the group members as processes join and
leave the group, and as they disconnect from and reconnect to the server. At each
of these events, the group facility revises ordinals to restore a one-to-one mapping
between n members and the positive integers [1,n].
Developers are responsible for the names of groups, and the API calls that join
groups. Administrators are responsible for configuring group communication
and running the group servers.
Group Communication
Within each member process, the group library connects to the group server.
While connected, the member and the group server exchange periodic protocol
messages. When disconnected, the member initiates reconnection.
To reduce the cost and complexity of this required communication (and for best
performance), we recommend that the group server and all group members run
in nearby geographical proximity to one another.
Group protocol communication depends on application definitions that define
endpoints and transports that connect members to the group server, and the
formats of group protocol messages.
To enable group communication, you must first add these definitions to the realm
definition, using the group setup script (see Using the Group Setup Script on
page 218). These application definitions are not visible in the realm server
configuration interface.
Running the Group Server
Beyond configuring group communication in the realm, the group server does not
require any further explicit administrative action.
The group server runs inside realm server processes. (The clients summary page
displays the group server as an internal client; you cannot disable nor purge it.)
The group server and all the group members that it coordinates must run within
one local area network. We do not recommend using the group facility across
routers and WANs.
Administrative Overview 217
|
Fault Tolerance
The group server is automatically fault-tolerant, if and only if both of these
conditions are true:
•
The primary realm server has a backup server.
•
The administrator supplied the backup server host and port information to
the group setup script when enabling groups.
The group server runs inside the primary realm server and (optionally) its backup
server—that is, the group server does not run in satellites nor in their backups.
Each realm server automatically determines whether it can and should run an
embedded group server—based on the realm configuration, and on the server’s
role (see Affiliated Realm Servers on page 75).
Group servers within a primary realm server and its backup server automatically
coordinate for fault-tolerant operation. Group members automatically failover
between these two servers.
Group members that failover to a secondary group server (within a backup realm
server process) remain with that group server (until it fails). In contrast, clients
that have migrated to a backup realm server automatically return to the regular
realm server when it again becomes available.
This can result in a situation where clients depend on regular server A for realm
information, but as group members they depend on backup server B to
coordinate groups. Although this divergence might seem counterintuitive, it is
the expected behavior.
218
| Chapter 13
Using the Group Setup Script
Administrators use init_groups.py (the group setup script) to modify the realm
definition within a running realm server, in order to enable groups.
Before running this script, ensure that your execution path environment variable
includes the product’s bin directory (to access the script).
init_groups.py [-u username -pw
[-a]
Syntax
password]
realm_svr_URL
primary_host:primary_port
[backup_host:backup_port]
[DELETE]
The script uses its arguments to define applications within the realm:
_GroupServerApp and _GroupClientApp. (If application definitions with these
names are already present in the realm, then the group setup script deletes them,
and replaces them with new definitions incorporating the script’s current
arguments.)
Table 65 Group Setup Script—Parameters (Sheet 1 of 2)
Parameter
Argument
Description
--user
-u
username
Credentials. Optional. (Required for JAAS
authentication.)
--password
-pw
password
When present, the group setup script authenticates itself
to the realm server using these credentials.
When present, these credentials must precede all
positional arguments.
When JAAS is enabled, username must be in authorization
group ftl-admin.
Using the Group Setup Script 219
|
Table 65 Group Setup Script—Parameters (Sheet 2 of 2)
Parameter
Argument
Description
Auto-Proceed. Optional.
-a
When present, the script resolves issues during the
deploy transaction by automatically proceeding (despite
any unsuccessful tests). For background information, see
The Deploy Transaction on page 112, and Unsuccessful
Test on page 114.
When absent, the script resolves issues by canceling the
deploy transaction.
realm_svr_URL
Realm server URL. Required.
The script contacts the realm server at this location, and
modifies its realm definition. Supply the location of the
primary realm server (see Connect Port on page 86).
primary_host:primary_port
Primary group server host:port. Required.
The hostname of the primary group server must be
identical to the hostname of the primary realm server.
Group members contact the primary group server at this
host and port.
backup_host:backup_port
Backup group server host:port. Optional.
The hostname of the backup group server must be
identical to the hostname of the primary realm server’s
backup server.
Group members contact the backup group server at this
host and port.
When present, the script deletes all group definitions
from the realm—which disables groups. See Disabling
Groups, below.
DELETE
Disabling Groups
To disable groups, execute this command line:
init_groups.py [-u
username -p password] realm_svr_URL DELETE
220
| Chapter 13
Group Server Monitoring Page
The Group Server monitoring page presents the status of the group server.
For descriptions of these fields, see Table 45, Client Page, on page 162.
This page also presents client monitoring statistics from the group server (see
| 221
Chapter 14
Transport Bridge
The transport bridge is an executable component that forwards messages among
transports.
Topics
•
Overview, page 222
•
Use Cases, page 224
•
Topologies, page 228
•
Transport Restrictions, page 230
•
Configuring Bridges, page 231
•
Using the Transport Bridge Executable, page 232
•
Fault Tolerance, page 235
•
Bridges among Dynamic TCP Meshes, page 236
•
Bridge Setup Script for Dynamic TCP Meshes, page 238
Configuration Interface
•
Bridges Summary, page 241
•
Configuring a Bridge Definition, page 242
•
Bridge Monitoring Summary, page 244
•
Bridge Status, page 245
Command Line Script
•
Bridge Setup Script, page 246
222
| Chapter 14
Transport Bridge
Overview
A transport bridge is a specialized daemon process that efficiently forwards
messages among sets of transports.
Functionality
You can configure a bridge with two or more terminals, called transport sets (or
more briefly, sets). You can configure each set with one or more transports.
A transport bridge forwards all messages in all directions. Whenever a message
arrives on any one of its transports, it immediately republishes that message on all
of the transports in all of the other sets. (That is, it does not forward the message on
other transports within the same set.)
The transports can be of the same type, or they can be of different transport types
(for example, you can bridge between shared memory and RDMA transports).
A transport bridge operates completely within a single realm. It forwards
messages among transports within the realm—but it cannot forward messages
between two different realms.
Transport bridges can forward one-to-many messages and one-to-one messages.
Transport bridges support one-to-one messages on transports that support inbox
abilities. However, bridges support this feature only when both clients use the
FTL library from release 2.x (or later); bridges do not support one-to-one messages
when clients use the library from release 1.1 (or earlier).
You can run two (or more) bridge processes for fault-tolerant operation. Although
this feature ensures automatic and quick recovery, failover might leave some
messages unforwarded.
Design Features
Low latency is a key feature of the transport bridge. The transport bridge
implementation is extremely fast and efficient. It forwards packets immediately—
even before all the packets of a message have arrived.
Transport bridges are transparent to your application programs. Clients do not
need to do anything different to communicate across a bridge, nor can they detect
whether a bridge mediates between them.
Overview 223
|
Latency
Although the transport bridge is efficient, it still adds an extra layer between
sending and receiving processes, which necessarily increases message latency.
In some situations, sending on several transports could result in less additional
latency than a bridge (at the cost of limiting maximum throughput). We
recommend empirical testing to optimize results for your specific application
needs and resources. For more information, see Multiple Transports on page 28.
| Chapter 14
Transport Bridge
Use Cases
Shifting Fanout for Efficiency
You can use a transport bridge to shift fanout closer to subscribers, for more
efficient use of WAN bandwidth. For example, in Figure 16, a publisher in New
York communicates with several subscribers in Boston using a static TCP
transport. In this situation, each subscriber initiates a separate connection to the
publisher, and each message crosses the WAN repeatedly (once per connection).
This duplication of data over a slow or expensive link could be undesirable.
Cli
en
T1
E1
E2
t
Boston
Client
T2
New York
E2
TCP
Bus
T2
Serv
er
Figure 16 Fanout over WAN (without Transport Bridge)
T2
E2
Client
Instead consider the arrangement of Figure 17, in which a transport bridge in
Boston connects to the New York publisher only once using a static TCP transport
over a WAN, and forwards messages to many subscribers using LAN bandwidth.
T4
E4
E4
Clie
nt
New York
T4
Boston
Client
T2
T3
T1
RDMA
Bus
t
Clien
Transport Bridge
E4
TCP
Bus
T4
E1
Figure 17 Transport Bridge: Fanout after WAN
Serv
er
224
Use Cases 225
|
Extending the Capabilities of a Transport
You can also use a transport bridge to extend the capabilities of a transport. For
example, in Figure 18, a publisher communicates with several subscribers on a
single host computer using a shared memory transport T1. You can communicate
with subscribers on other computers across a LAN by configuring a multicast
transport T2, and a transport bridge between T1 and T2. (The transport bridge
must run on the computer that hosts the shared memory segment of T1.)
Figure 18 Transport Bridge: Extending Capabilities
SM1
SS1
P
E2
T2
T1
T1
SM
2
E2
E1
E1
T2
T1
E1
SS4
T2
E2
B
T2
T1
A
mcast
Bus
SM3
Transport Bridge
shm
Bus
T2
SM
4
E2
T1
T2
E2
SM 5
E1
SS2
T1
E1
SS3
Multiple Transports
Until this point, we have presented examples in which the bridge forwards
between two transport sets, each containing only one transport. You can also
configure a bridge with several transports in a set.
For example, return to Figure 18, and consider that an enterprise might
communicate over several multicast groups (not just one). To forward messages
on all of them, the bridge requires a separate transport for each multicast send
group. You can configure the bridge to include all of those multicast transports in
transport set B.
| Chapter 14
Transport Bridge
A bridge does not forward messages among the several transports in a transport
set—only from the transport set where the message arrives, to all the transports in
all the other sets. Consider the implications in the context of the current example.
When a message arrives on T1, the bridge forwards it on all the transports in
transport set B. When a message arrives on any one of the multicast transports in
B, the bridge does not forward the message on any of the other multicast
transports in B—it forwards only on T1 (which is in set A).
The transports in a set need not be of the same transport type.
Crossing the Boundary of Shared Memory
Access to a shared memory transport is limited to processes running on the
computer that hosts the transport’s shared memory segment. To escape this
natural boundary, you can arrange two transport bridges in series. Figure 19 on
page 226 depicts such an arrangement, connecting shared memory transports on
separate host computers.
One transport bridge must run on the computer that hosts the shared memory
segment of T1, while the other bridge must run on the computer that hosts the
shared memory segment of T4. The two bridges communicate with one another
over a fast RDMA transport.
Figure 19 Transport Bridge: Connecting Shared Memory on Two Computers
SS1
E1
Host 1
SS6
Host 2
E1
T1
T4
T4
Transport Bridge
shm
Bus
T4
T3
T1
T2
Transport Bridge
RDMA
Bus
T1
T4
E1
SS
9
T1
E1
E1
SS 2
SS3
SS8
See Also
E1
E1
T1
shm
Bus
SS7
E1
P
T4
226
Latency on page 223.
Use Cases 227
|
Isolated Spokes
Transport bridges can connect partner enterprises that must cooperate, and yet
remain separate. Figure 20 on page 227 shows a central control hub for the main
enterprise, with spokes to partner enterprises. Although each partner enterprise
must share data with the main hub, the partners must not share data with one
another.
Figure 20 Transport Bridge: Common Hub with Mutually-Isolated Spokes
Hub Host
RDMA
Hub
Bus
Hub
Transport
Bridge
TCP
Spoke
Bus 1
Spoke
Transport
Bridge
shm
Local
Bus
TCP
Spoke
Bus 2
Spoke
Transport
Bridge
RDMA
Local
Bus
TCP
Spoke
Bus 3
Spoke
Transport
Bridge
mcast
Local
Bus
Spoke Host 1
Spoke Host 2
Spoke Host 3
This use case is interesting in two respects:
•
It is an example of a complex bridge topology (see Hub and Spoke Bridges on
page 229).
•
It uses transport sets to isolate data. The hub transport bridge configures the
RDMA hub transport in one transport set, and collects all the spoke transports
in a second transport set. This configuration forwards data from the hub bus
to all spoke buses, and forwards data from each spoke bus to the hub bus.
Meanwhile, it isolates data from the various spoke buses, so it does not
forward to other spokes.
| Chapter 14
Transport Bridge
Topologies
Transport bridges support only the three topologies presented in this section.
Any topology that includes any kind of loop is prohibited.
One Bridge
The basic topology is a single bridge between two transports; see Figure 21.
Figure 21 Transport Bridge Topology—One Bridge
Host 1
Host 2
T1
T2
Transport Bridge
Bus
Bus
You may extend this topology by adding transport sets, or by adding transports
to the transport sets.
Two Serial Bridges
Two serial bridges are useful for bridging shared memory transports on different
hosts; see Figure 22. (For more information about this use case, see Crossing the
Boundary of Shared Memory on page 226.)
Figure 22 Transport Bridge Topology—Two Bridges
Host 1
Host 2
T3
T1
Bus
Transport Bridge
Bus
T4
Transport Bridge
T2
228
Bus
Topologies 229
|
to the transport sets.
You may not extend this topology by adding a third serial bridge.
Hub and Spoke Bridges
Hub and spoke bridges are useful for connecting partner enterprises, especially at
remote sites (for more information, see the use case Isolated Spokes on page 227).
Figure 23 Transport Bridge Topology—Hub and Spoke Bridges
Hub Host
Hub
Bus
Hub
Transport
Bridge
Spoke Hosts
Spoke
Bus 1
Spoke
Transport
Bridge
Local
Bus
Spoke
Bus 2
Spoke
Transport
Bridge
Local
Bus
Spoke
Bus 3
Spoke
Transport
Bridge
Local
Bus
to the transport sets. You may extend this topology by adding more spokes (each
consisting of a spoke bus, a spoke bridge, and a local bus).
You may not extend this topology by adding a third serial bridge—neither to the
hub bus, nor to any local bus. You may not extend this topology by adding a
second branching spoke bridge to any spoke bus.
230
| Chapter 14
Transport Bridge
Transport Restrictions
•
Transport bridges support only bidirectional transports. For example, a bridge
cannot support a multicast transport configured with a send group but
without a listen group (nor vice versa).
•
Transport bridges support only non-blocking transports. A transport that
blocks could impede data flow through the bridge.
Configuring Bridges 231
|
Configuring Bridges
You can arrange several bridges within a realm. Each bridge requires a separate
bridge definition with a distinct bridge name, at least two transport sets, and at
least one transport in each set.
Adding Bridge Definitions
To configure bridge definitions, administrators can use either the realm server’s
bridge configuration GUI (see Bridges Summary on page 241 and Configuring a
Bridge Definition on page 242) or the init_bridge.py script (see Bridge Setup
Script on page 246).
Configuring a bridge definition (in either way) automatically embodies the bridge
in a bridge application definition within the realm. Bridge applications supply the
bridge server processes with instructions for binding their transports and
endpoints. (The applications summary page displays bridge applications as
internal applications; you cannot modify them through the application
configuration GUI—only through the bridge configuration GUI.)
Use Transports Uniquely
A transport can be in at most one transport set within a bridge definition.
You may use the same transport definition in more than one bridge. However, it is
your responsibility to avoid creating a bridge topology that contains loops.
232
| Chapter 14
Transport Bridge
Using the Transport Bridge Executable
Administrators use tibbridge (the transport bridge command line executable) to
start a bridge process. (The clients summary page displays a bridge process as an
internal client; you cannot disable nor purge it.)
Each bridge process can implement one or more bridge objects (as defined in the
realm). These bridge objects are independent—even though one process
implements them all, messages do not cross from one bridge to another.
If the bridge objects (or the transport definitions that they use) change, you must
explicitly restart the affected bridge process.
Table 66 tibbridge Executable (Sheet 1 of 2)
Parameter
Arguments
Description
--realmserver
URL
Required.
URL of the realm server.
-rs
The bridge process contacts the realm server at this
location to receive its bridge objects. Supply the
location of the primary realm server or a satellite
server (see Connect Port on page 86).
-s
URL
Optional.
URL of the backup realm server.
If the regular realm server is unavailable, the bridge
process contacts the backup realm server at this
location to receive its bridge objects. Supply the
location of the backup realm server (see Connect
Port on page 86).
Using the Transport Bridge Executable 233
|
Table 66 tibbridge Executable (Sheet 2 of 2)
Parameter
Arguments
Description
--name
bridge_name
Optional (zero or more).
Bridge name.
-n
A bridge process implements one or more bridge
objects.
You may supply the name of a bridge object that this
process implements.
To implement several bridge objects in one process,
supply each bridge name as a separate command
line argument (that is, introduce each one with the
--name parameter).
When absent, the process implements only the
bridge named default.
--trace
level
Optional.
When present, the bridge process outputs trace
messages to stderr. You may specify any of the
standard log level strings (see Log Levels in the
book TIBCO FTL Development).
-t
When omitted, the process does not output trace
messages.
Print command line usage.
--help
-h
--password-file
-pf
path
Optional. (Required for JAAS authentication.)
When present, the bridge process reads a username
and password from the file at path, and authenticates
itself to the realm server using those credentials. For
details, see Password File on page 83.
Password File
configure credentials for the bridge process.
The bridge process authenticates itself to the realm server using credentials that it
reads from an ASCII password file (see --password-file on page 233).
234
| Chapter 14
Transport Bridge
Fault Tolerance 235
|
Fault Tolerance
You can run two (or more) bridge processes for fault-tolerant operation. Although
this feature ensures automatic and quick recovery, failover might leave some
messages unforwarded.
Fault-tolerant bridges rely on the group facility. When the group facility is
enabled, bridge processes use it to coordinate fault tolerance. (If the group facility
is not enabled, each bridge process operates as an independent entity.)
Task J Arranging a Fault-Tolerant Transport Bridge
1. Enable the group facility; see Using the Group Setup Script on page 218.
2. Ensure appropriate network connectivity, so that each bridge process can
communicate with the group server over a static TCP transport.
3. Configure bridges; see Configuring Bridges on page 231.
4. Start two bridge processes on separate host computers. Specify the same
command line arguments to each process (see Using the Transport Bridge
Executable on page 232). The FTL group facility automatically enables only
one bridge process at a time.
Shared Memory Transports and Fault-Tolerant Bridges
Shared memory transports require that all client processes run on the same host
computer as the shared memory segment; as a result, when bridging shared
memory transports, you cannot use redundant processes on separate host
computers as a fault tolerance mechanism. Instead you could arrange fault
tolerance by immediately and automatically restarting the bridge process.
236
| Chapter 14
Transport Bridge
Bridges among Dynamic TCP Meshes
A dynamic TCP transport establishes a bus with full mesh topology among all its
endpoints—as long as their applications connect to a single realm server process.
When your enterprise uses satellite realm servers, a single dynamic TCP transport
establishes a separate mesh for each satellite; each mesh includes all the
applications that are clients of one of the affiliated realm servers. You can use a
transport bridge to link those otherwise disjoint meshes.
It is possible to define a transport bridge for dynamic TCP meshes similarly to
other bridges. However, structural constraints on such a bridge allow us to
simplify its definition. We offer a specialized setup script that takes advantage of
that structure; see Bridge Setup Script for Dynamic TCP Meshes on page 238.
For more background information, see Dynamic TCP Transport on page 60.
Principles of Operation
Figure 24 Bridging for Dynamic TCP Meshes
Satellite 1 Location
Primary Location
Bridge Server
P
ir C
Pa
ne
on
on
cti
Bridge Server
S1
Satellite 1
Mesh
Bridge Server
S1 Backup
Primary
Mesh
Bridge Server
P Backup
Satellite 2 Location
Bridge Server
S2
Bridge Server
S2 Backup
Satellite 2
Mesh
Figure 24 depicts a general use case of a dynamic TCP bridge. This enterprise
includes three locations—the primary location (left) and two satellite locations
(right)—each with an affiliated realm server process (not shown). The realm
defines a single dynamic TCP transport, which establishes a mesh at each
location; the meshes are disjoint from one another.
Bridges among Dynamic TCP Meshes 237
|
To bridge the meshes, we need a bridge server at each location (orange), and a
bridge definition that links the locations using a static TCP transport. The static
TCP transport connects from the primary bridge server to each of the satellite
bridge servers (solid lines).
The fault-tolerant scenario adds a backup bridge server at each location (light
orange). Both bridge servers at the primary location connect to both bridge
servers at each satellite location (solid lines and dashed lines).
238
| Chapter 14
Transport Bridge
Bridge Setup Script for Dynamic TCP Meshes
Administrators can use init_dtcp_bridge.py to define transport bridge objects
that link dynamic TCP meshes in remote locations.
For background information, see Bridges among Dynamic TCP Meshes on
page 236.
Syntax
init_dtcp_bridge.py [-u
[-a]
[-d]
username -pw password]
realm_svr_URL
dtcp_transport_name
bridge_tcp_port
{ satellite_bridge_host[:backup_satellite_bridge_host] }+
Table 67 init_dtcp_bridge Script (Sheet 1 of 2)
Parameter
Arguments
Description
--user
-u
username
Credentials. Optional. (Required for JAAS
authentication.)
--password
-pw
password
When present, the bridge setup script authenticates itself
to the realm server using these credentials.
When present, these credentials must precede all
positional arguments.
When JAAS is enabled, username must be in authorization
group ftl-admin.
-a
When present, the script resolves issues during the
deploy transaction by automatically proceeding (despite
any unsuccessful tests). For background information, see
The Deploy Transaction on page 112, and Unsuccessful
Test on page 114.
When absent, the script resolves issues by canceling the
deploy transaction.
Bridge Setup Script for Dynamic TCP Meshes 239
|
Table 67 init_dtcp_bridge Script (Sheet 2 of 2)
Parameter
Arguments
Description
Delete a bridge. Optional.
-d
When present, the script deletes the definition from the
realm (instead of adding it). The subsequent parameters
indicate the bridge definition to delete; they must exactly
match the parameters of an existing bridge definition.
This command also deletes transports that the script
created automatically when defining the bridge.
realm_svr_URL
The script contacts the realm server at this location, and
modifies its realm definition. Supply the location of the
primary realm server (see Connect Port on page 86).
dtcp_transport_name
Dynamic TCP transport name. Required.
The script defines a bridge object that links the otherwise
disjoint meshes that arise from this transport. This
transport must already be defined in the realm.
bridge_tcp_port
TCP port number. Required.
The script automatically defines a static TCP transport
that listens and connects on this TCP port number. The
transport links the bridge servers.
satellite_bridge_host
Host of the main bridge server in the satellite location.
Required.
You may specify a bridge server in one or more satellite
locations.
backup_satellite_bridge_host
Host of the backup bridge server in the satellite location.
Optional.
When present, use the colon character (:) to separate it
from the main bridge server host.
You may specify a backup bridge server for any main
bridge server.
240
| Chapter 14
Transport Bridge
Deleting a Bridge Definition for Dynamic TCP Meshes
To delete a bridge that you defined using this script, use this script again, with the
-d parameter.
We recommend this method (rather than deleting the definition using the GUI) to
avoid incomplete clean-up of automatically-defined transports.)
Adding Satellites to a Bridge for Dynamic TCP Meshes
Because this script automatically defines transports, you cannot directly add new
satellites bridge hosts to an existing bridge. Instead, delete the exiting bridge
definition, then redefine the bridge to include the new and existing satellite
bridge hosts.
Example 3 Adding Satellite Bridge Servers for Dynamic TCP Meshes
1. Suppose you have defined a bridge using this command:
init_dtcp_bridge.py myrealmhost:5238 tport1 9372 br1:br2-bkp
2. You must first remove that definition:
init_dtcp_bridge.py -d myrealmhost:5238 tport1 9372 br1:br2-bkp
3. Then redefine the bridge to include the new satellite bridge hosts.
init_dtcp_bridge.py myrealmhost:5238 tport1 9372 br1:br2-bkp br3:br4-bkp
Bridges Summary 241
|
Bridges Summary
The Bridges summary page displays bridge definitions in the realm, and lets you
create new bridge definitions.
242
| Chapter 14
Transport Bridge
Configuring a Bridge Definition
The Bridge definition page presents the details of a bridge definition, and lets you
modify the definition.
Table 68 Bridge Definition—Components (Sheet 1 of 2)
Parameter
Description
Common Components
Name
Required.
Name of the bridge.
Bridge names must be globally unique within the realm.
Configuring a Bridge Definition 243
|
Table 68 Bridge Definition—Components (Sheet 2 of 2)
Parameter
Description
Description
Optional.
You can use this text field as a comment to describe the bridge and
Transport Sets
Required.
You must define at least two transport sets.
Transport Names
Required.
For each transport set, you must define at least one transport name. The
transports must already be defined in the realm.
244
| Chapter 14
Transport Bridge
Bridge Monitoring Summary
The Bridges summary page lists the bridge processes (bridge processes are clients
of the realm server).
Table 69 Bridges Summary
Column
Description
Client ID
The realm server assigns each bridge client a unique identifier.
Name
The bridge name string.
Host
The hostname string of the bridge client’s host computer (if available).
Bridge Status 245
|
Bridge Status
The bridge status monitoring page presents the status of a bridge.
Table 70 Bridge Status Page
Field
Description
Bridge Name
Bridge name (defined in the realm server).
For all other fields, see Table 45, Client Page, on page 162.
This page also presents client monitoring statistics from the bridge process (see
246
| Chapter 14
Transport Bridge
Bridge Setup Script
The easiest way to define a bridge is by using the realm’s GUI configuration
interface (see Configuring a Bridge Definition on page 242). Alternatively,
administrators can use init_bridge.py (the bridge setup script) to define
transport bridge objects within the realm.
Syntax
init_bridge.py [-u username -pw
[-a]
password]
realm_svr_URL
[bridge_name]
SET transport_name [transport_name]*
SET transport_name [transport_name]*
[SET transport_name [transport_name]* ]*
[DELETE]
Table 71 init_bridge Script (Sheet 1 of 2)
Parameter
Arguments
Description
--user
-u
username
Credentials. Optional. (Required for JAAS authentication.)
--password
-pw
password
When present, the bridge setup script authenticates itself to the
realm server using these credentials.
When present, these credentials must precede all positional
arguments.
When JAAS is enabled, username must be in authorization group
ftl-admin.
-a
When present, the script resolves issues during the deploy
transaction by automatically proceeding (despite any
unsuccessful tests). For background information, see The Deploy
Transaction on page 112, and Unsuccessful Test on page 114.
When absent, the script resolves issues by canceling the deploy
transaction.
Bridge Setup Script 247
|
Table 71 init_bridge Script (Sheet 2 of 2)
Parameter
Arguments
Description
realm_svr_URL
The script contacts the realm server at this location, and modifies
its realm definition. Supply the location of the primary realm
server (see Connect Port on page 86).
bridge_name
Bridge name. Optional (at most one).
When present, the script defines a bridge object with this name.
When absent, the script defines a bridge named default.
Bridge names must be unique. If a bridge with the same name
already exists, the script deletes its definition and replaces it with
a new definition.
transport_names
SET
Begin a new transport set. Required.
You must define at least two transport sets. Introduce each set with
the parameter keyword SET, then supply its transport names
(separated by space characters).
For each set, supply at least one transport name. The transports
must already be defined in the realm.
DELETE
bridge_name
Delete a bridge. Optional.
When present, the script deletes the definition for bridge_name from
the realm (instead of adding it).
See Also
Configuring Bridges, page 231
248
| Chapter 14
Transport Bridge
| 249
Chapter 15
Persistence (Stores and Durables)
Stores and durables provide persistent message interest and persistent message
streams.
Topics
•
Feature Overview, page 251
•
Stores for Delivery Assurance, page 253
•
Stores for Apportioning Message Streams, page 259
•
Persistence Servers and Cluster, page 260
•
Realm Configuration Structure, page 263
•
Persistence Server Transports, page 265
•
Publisher Mode, page 267
•
Durable Behavior, page 268
Configuration Interface
•
Configuring the Realm Persistence Cluster, page 270
•
Configuring a Persistence Server Definition, page 272
•
Configuring a Store Definition, page 275
•
Configuring a Durable Definition, page 277
•
•
Configuring Durable Subscribers within an Application Instance, page 281
•
Persistence Servers Monitoring Summary, page 283
•
Monitoring a Persistence Server, page 286
•
Persistence Stores Monitoring Summary, page 289
250
| Chapter 15
•
Monitoring a Store, page 290
•
Monitoring a Shared Durable, page 292
Using and Administering Persistence Servers
•
Starting a Persistence Server, page 294
•
tibstore Command Line, page 295
•
Saving and Loading Persistence State, page 298
•
Purging Durables or Stores, page 301
Feature Overview 251
|
Feature Overview
For an intuitive introduction and terminology, see the Persistence chapter in
TIBCO FTL Concepts.
Purpose
Persistence is the potential to store a message between sending and receiving it.
The persistence infrastructure of stores and durables can serve two purposes—
delivery assurance, and apportioning message streams.
Delivery
Assurance
An ordinary subscriber receives messages from a publisher only when a transport
connects the subscriber with that publisher. That is, an ordinary subscriber cannot
receive a message through a direct path transport unless both of these conditions
hold at the time that the publisher sends the message:
•
The subscriber object exists.
•
The transport is connected.
Persistence lets subscribers receive every message with high assurance, despite
temporary lapses in these conditions. For example, a persistence store can retain
data for subscriber recovery after application exit and restart, temporary network
failure, or application host computer failure.
Stores can retain data indefinitely, until subscribers acknowledge delivery. (In
contrast, even reliable transports retain data only for a finite reliability interval.)
For this purpose, administrators configure stores with non-shared durables.
Apportioning
Message
Streams
A shared durable can apportion a message stream among a set of cooperating
subscribers so that only one subscriber receives and processes each message, but
acting together the subscribers process every message in the stream.
For this purpose, administrators configure stores with shared durables.
Architecture for Delivery Assurance
FTL features high-speed message delivery with low latency; using stores for
delivery assurance is consistent with this overall architectural goal:
252
| Chapter 15
•
Delivery assurance using non-shared durables operates alongside regular
direct-path delivery.
Transports carry messages directly from publishers to subscribers—without
an intermediary hop through a persistence server, which would add message
latency. Separate transports carry messages from publishers to a store in the
persistence servers, which stores them for as long as subscribers might need to
recover them.
•
Persistence servers store message data in process memory, avoiding latency
associated with disk I/O.
Replication of data across a cluster of several servers protects against
hardware or network failures on a small scale. (However, this replication
scheme cannot guarantee delivery after catastrophic failures.)
•
FTL persistence architecture flexibly accommodates diverse application
requirements.
Publisher quality of service—for each store, administrators can balance
appropriately between performance requirements and the need to confirm
message replication.
Subscriber acknowledgement—within application programs, subscribers can
acknowledge message delivery automatically or explicitly; administrators can
configure durables to receive individual acknowledgements synchronously,
or in batches (asynchronously).
Architecture for Apportioning Message Streams
Using persistence stores to apportion message streams emphasizes throughput
rather than the lowest latency.
Delivery through shared durables replaces direct-path delivery. The persistence
server that apportions the message stream is an intermediary hop, which adds
message latency.
Coordination
Administrators and application developers must coordinate the details of
durables; see Durable Coordination Form on page 320.
Stores for Delivery Assurance 253
|
Stores for Delivery Assurance
Topology
When using a store for delivery assurance, the store is similar a second transport.
Like the direct path, it enables message communication among a network of
endpoints. It operates in parallel with direct-path transports, as an additional
path from publishers to subscribers.
Because the store offers a redundant path, we say that the store backs the direct
paths. Depending on our focus, we can also say that the store backs the network of
endpoints, or that it backs the message stream that travels among those endpoints.
Figure 25 Store as Redundant Message Path
T
E
App
E
T
App
Direct Path
Bus
Store
Figure 25 depicts a direct path through the transport bus, and another path from
endpoint to endpoint through a store. (Conceptually, communications to and
from the store travel through the endpoint instances; FTL arranges a
communication mechanism for this path.)
Direct Path Requirement for Non-Shared Durables
For delivery assurance, you must configure a direct path. We do not support
configurations in which a store is the only path between a publishing endpoint
and a subscribing endpoint.
(This requirement does not apply when using a store to apportion a message
stream—only for delivery assurance.)
Retention and Delivery
A store adds value by strengthening message delivery assurances. You could
imagine a store as a bus that can retain its message stream for subscribers that are
temporarily unavailable.
| Chapter 15
Figure 26 Store for Message Recovery
T
E
App
T
E
App
T
E
Direct Path 3
App
254
Bus
1
2
Store
Store
In the first frame of Figure 26, the durable subscriber is unavailable, so it misses
messages from the publisher; the store collects those messages (1). In the second
frame, the durable subscriber resumes, recovers the missed messages from the
store (2), then continues receiving messages directly from the publisher (3).
Larger Networks of Endpoints
Stores connect endpoints to endpoints.
Earlier diagrams showed the store connecting one publisher endpoint to one
subscriber endpoint. More generally, a store can connect many publisher
endpoints (each with many publishers) to many subscriber endpoints (each with
many subscribers).
The store in Figure 27 collects messages from two publishers on endpoint E1 (left).
Two durable subscribers on endpoint E2 (right) can recover those messages from
the store.
In accord with the direct path requirement, a direct path connects each of the two
E1 publishers to each of the two E2 subscribers (see Direct Path Requirement for
Non-Shared Durables on page 253).
|
Figure 27 Store Serves Several Publishers and Subscribers
Durable Subscribers
T
E1
App
E2
T
Ap
p
Publishers
Direct Path
Bus
T
T
E1
Ap p
Ap
p
E2
Durable 1
Durable 2
Store
Notice that each of the durable subscribers in Figure 27 depends on a unique
non-shared durable within the store.
Combined Message Stream
A store collects messages from all its publishing endpoints, and merges them into
a combined message stream. The store then ensures that all of its subscribers
receive every message of that combined message stream. (If a subscriber has a
content matcher, it receives every matching message.)
In Figure 27 the store merges the message streams from the two publishers, and
feeds the combined stream to both subscribers. Each subscriber then receives the
entire combined message stream.
Multiple Stores
A store can serve as a redundant message path for exactly one combined message
stream. When a suite of application programs communicate using two or more
disjoint message streams, use a separate store to back each of the message
streams.
While stores can potentially contain large quantities of message data, each store is
itself a lightweight object. When the situation requires multiple stores, use as
many as is appropriate. (Using one store inappropriately to back two or more
direct message streams is a configuration error.)
| Chapter 15
Two message streams are disjoint when they travel among disjoint networks of
endpoints. For example, Figure 28 depicts a suite of three application programs;
App1 sends a stream of messages from endpoint E1 to endpoint E2 in App2;
App2 in turn sends a (different) stream of messages from endpoint E3 to endpoint
E4 in App3. The two message streams are disjoint (even though E2 and E3 are
both endpoints in App2). Because the message streams are disjoint, each requires
its own store.
T
E3
T
Bus
E4
T
E2
E1
Direct Path
App2
App3
Direct Path
T
App1
Figure 28 Two Stores
Bus
Store1
Store2
Larger Disjoint Networks of Endpoints
Figure 28 depicted only one publisher feeding into each store, and only one
subscriber depending on each store. Figure 29 depicts the same application suite
in a more complex configuration, with two instances of each program.
E3
T
T
T
T
E3
E1
E4
App3
App1
E4
Direct Paths
App3
T
App2
T
Store1
App2
E2
T
Direct Paths
E2
T
E1
Figure 29 Two Stores with Many Publishers and Subscribers
App1
256
Store2
Figure 29 shows that each of the two stores serves a separate network of
endpoints. Store1 serves E1 and E2, while Store2 serves E3 and E4.
|
Notice that Figure 29 satisfies the direct path requirement (see Direct Path
Requirement for Non-Shared Durables on page 253). Each E1 publisher has a
direct path to every E2 subscriber; similarly, every E3 publisher has a direct path
to every E4 subscriber.
Store1 merges the message streams from all the E1 publishers, and guarantees
that all the E2 subscribers receive all the messages in that combined message
stream. Similarly, Store2 merges the message streams from all the E3 publishers,
and guarantees that all the E4 subscribers receive all the messages in that
combined message stream.
Violating the Direct Path Requirement
The preceding examples all satisfy the direct path requirement (see Direct Path
Requirement for Non-Shared Durables on page 253). Violating the direct path
requirement is a configuration error, and causes incorrect results.
Figure 30 illustrates this error by modifying the example of Figure 28 to
erroneously use one store instead of two.
Direct Path 2
T
E3
E1
T
!
E4
Bus
T
E2
App2
App3
Direct Path 1
T
App1
Figure 30 Erroneously Using One Store Instead of Two
Bus
Store
Configuration Error
In this erroneous configuration Store1 collects messages from publishers at E1 in
App1 and E3 in App2, and merges them into a combined message stream. Then
Store1 ensures that all of its subscribers—at E2 in App2 and E4 in App3—receives
every message of the combined message stream. That is, messages that App1
sends to App2 arrive (erroneously) at App3; messages that App2 sends to App3
also arrive (erroneously) at App2.
These results are clearly incorrect. They do not match our intent—compare
Figure 30 with Figure 28 on page 256. Furthermore, this outcome results directly
from violating the direct path requirement:
•
Store1 connects E1 to E4—without any direct path connecting them.
•
Store1 connects E3 to E2—without any direct path connecting them.
258
| Chapter 15
Durable Collision
Each non-shared durable can serve at most one durable subscriber object at a
time. The store resolves collisions in favor of the most recent durable subscriber.
For example, if a durable subscriber in process A is using durable D, and a new
durable subscriber in process B subsequently claims D, then B wins the durable
from A. The store forces subscriber A to close.
The assumption behind this behavior is that the older durable subscriber is
malfunctioning, and the newer one has started in order to replace it.
Default Durable
You can use the default durable to let any application benefit from delivery
assurance—even applications that do not explicitly supply a durable subscriber
name in their create subscriber calls.
To use the default durable, administrators may map the default subscriber name
(_default) to a durable in one or more application instance definitions.
Restrictions
See Also
•
Each application instance definition supports at most one default durable per
endpoint. That is, for each application endpoint, each application instance
definition can map the default subscriber name to at most one durable name.
(However, separate application instance definitions can map their respective
default subscribers to different durable names.)
•
At any moment, at most one running process can claim a specific non-shared
durable. (This restriction applies to all non-shared durables—but we
recommend special attention to prevent inadvertent violations by processes
that use default durables.)
Configuring a Default Durable, page 282
Stores for Apportioning Message Streams 259
|
Stores for Apportioning Message Streams
Topology
When using a store to apportion a message stream, the store is an intermediary
hop between publishing and subscribing applications. In Figure 31, notice the
absence of any direct path—the store is the only path from the publishing
endpoint to the subscribing endpoints. (The direct path requirement does not
apply when using a store to apportion a message stream—only for delivery
assurance.)
Figure 31 Store as Apportioning Intermediary
Pub
Sub
Sub
Sub
E
E
E
E
Store
Shared Durable
Apportioning
The shared durable in Figure 31 apportions the message stream among its
subscribers. That is, each subscriber receives a portion of the message stream,
rather than every message. Exactly one subscriber consumes each message in the
message stream.
Acknowledgment and Redelivery
A subscriber acknowledges each message it receives. The shared durable tracks
those acknowledgements. If a subscriber disconnects leaving one or more
messages unacknowledged, the shared durable redelivers those messages to
other subscribers.
260
| Chapter 15
Persistence Servers and Cluster
A persistence server (or store server) is a process that implements one or more stores.
Several servers can cooperate as a cluster.
The servers within the cluster communicate among themselves to replicate
message data and acknowledgement data. Replication ensures that the cluster can
continue to deliver messages to subscribers, even when some of the servers are
unavailable.
Administrators define the cluster and its servers within the realm. Each realm can
define at most one cluster. The cluster consists of a set of store servers. Each server
must run on a dedicated host computer.
The cluster (as a whole) maintains a set of stores, replicating their data among its
servers for fault tolerance.
Quorum and Leader
The cluster can interact with clients only when a quorum of servers exists (see
Quorum Conditions—General Rule, below). This requirement ensures correct
replication and fault tolerance (see Fault Tolerance, below).
When a quorum exists, one of the servers takes the role of leader—the server that
interacts with clients. All other servers in the quorum replicate the leader’s data,
but do not interact with clients.
Administrators can set the weight of each server to determine an order of relative
preference in which servers become the leader.
Quorum Conditions—General Rule
A valid quorum ensures correct replication and fault tolerance. As a general rule,
a group of candidate servers must satisfy all three of the following conditions to
form a valid quorum (for special exceptions, see Quorum Behaviors on page 261):
•
Majority The number of candidate servers that satisfy these conditions must
be strictly greater than half of the number of servers in the cluster definition
(that is, a simple majority).
•
Reachable A majority of the defined servers must be running and able to
communicate with one another.
•
Non-Empty A majority of the defined servers must be non-empty. (A server
process is empty when its process starts or restarts without loading saved state.
A server that has successfully joined a quorum is no longer empty.)
Persistence Servers and Cluster 261
|
Cluster Size
For delivery assurance with fault tolerance we recommend a minimum cluster
size of 3 servers, so that a quorum can exist even when one server is unavailable.
A cluster of 2 servers is invalid, because when one server is unavailable, the
remaining server cannot form a quorum on its own; it is an error to configure only
2 servers.
For apportioning messages streams, a cluster of only 1 server is a valid
configuration.
Quorum Behaviors
Cluster Start
When the cluster starts for the first time (that is, all the servers are empty), the
servers wait until all the servers in the cluster have started, and are running
simultaneously. Then they constitute a quorum for the first time, and can begin
interacting with clients to store messages.
Steady State
After forming that initial quorum, client interaction continues while the quorum
exists (that is, a majority of servers continue to satisfy all three conditions of
Quorum Conditions—General Rule on page 260).
Rejoining the Quorum
A server can rejoin an existing quorum—for example, after that server restarts, or
becomes reachable (after recovery from network segmentation). The rejoining
server copies the data state of the quorum leader.
The current leader remains in place, even when the rejoining server has higher
weight. That is, weights are relevant only for leader election (which occurs only
when the quorum does not already have a leader).
Reforming a Quorum
If the servers no longer satisfy the quorum conditions, client interaction stops.
The quorum must reconstitute through any of the scenarios in Table 72.
262
| Chapter 15
Table 72 Reforming a Quorum
Scenario
Description
Complete
The cluster can form a quorum of non-empty servers (that is, they satisfy all three
conditions of Quorum Conditions—General Rule on page 260). For example, this
scenario can occur after recovery from network segmentation; or after suspending
the cluster, saving the state of its servers, and finally, restarting the servers.
Force Quorum
A majority of the defined servers are reachable, but the candidates cannot satisfy
the non-empty condition. After verifying preconditions, the administrator may
force a quorum (using the realm server monitoring interface). For more details,
see Forcing a Quorum on page 284.
The servers in the forced quorum copy the most recent message data state.
Fault Tolerance
Replication of data among a quorum of servers ensures that the cluster as whole
remains complete and correct, despite temporary outage of some of its servers.
Note that this level of fault tolerance does not support disaster recovery.
Fault tolerance applies only to stores that contain only non-shared durables.
We recommend that you insulate each server host from the other servers and the
factors that might make them unavailable (for example, ensure that server hosts
rely on separate power circuits and separate network infrastructure).
We do not recommend locating server hosts at geographically distant sites, which
would increase communication latency.
Realm Configuration Structure 263
|
Realm Configuration Structure
The realm definition schematic in Figure 32 indicates five configuration tasks for
stores and durables (numbers correspond to the task list below).
Figure 32 Configuring Durables in an Application
Persistence Cluster
Name: App 2P
Preload Formats:
Endpoints:
Format 1
1
R
Persistence
Servers
RI
Format 2
Endpt 1
S
Format 3
SI
4
Store 1
Instance: default
R
R
RI
RI
S
S
SI
SI
Endpt 1
Tport 1
2
5
Durable Subscribers
Store 1
3
Subscriber Name 1
Durable 1
Durable 1
Subscriber Name 2
Durable 2
Durable 2
...
...
1. Configure the store servers that make up the cluster.
For concepts, see Persistence Servers and Cluster on page 260.
For the configuration interface, see Configuring the Realm Persistence Cluster
on page 270, and Configuring a Persistence Server Definition on page 272.
264
| Chapter 15
2. Configure the stores within the cluster.
For concepts, see Publisher Mode on page 267.
For the configuration interface, see Configuring the Realm Persistence Cluster
on page 270, and Configuring a Store Definition on page 275.
3. Configure the durables within each store.
For concepts, see Durable Behavior on page 268.
For the configuration interface, see Configuring a Store Definition on
page 275, and Configuring a Durable Definition on page 277.
4. Associate application endpoints with stores, as appropriate.
For concepts and the configuration interface, see Configuring Persistence
Stores within the Application Definition on page 280.
5. Map durable subscribers to durables.
For concepts and the configuration interface, see Configuring Durable
Subscribers within an Application Instance on page 281.
Persistence Server Transports 265
|
Persistence Server Transports
Each persistence server uses two kinds of special-purpose transport:
•
The cluster transport communicates between the server and other servers in the
cluster.
•
The client transport communicates between the server and its client processes.
Administrators must configure the details of these transports as part of the
persistence server definition (rather than as separate transport definitions).
To configure these transports, see Cluster Transport & Client Transports on
page 273.
Alternate Client Transport
Consider a heterogeneous environment in which the client host computers have
different transport capabilities. For example, some hosts support RDMA
transports, while others do not. For best performance, each client would use the
fastest available transport type (and a single client transport has one type, either
RDMA or static TCP—it cannot combine the two).
In such situations you can define a second client transport—the alternate client
transport—and assign clients on specific hosts to use that alternate transport. All
other clients use the regular client transport.
To configure this transport, see Alternate Client Transport on page 274.
Client Transport and Non-Blocking Send
Administrators can choose whether the client transport uses blocking or
non-blocking send—but this setting affects only the client end of the transport
(the server end always uses non-blocking send).
In general, this choice is relevant only when the publisher mode (see Publisher
Mode on page 267) is Store – Send – No Confirm (because otherwise the
application publishing rate is limited by confirmations from the persistence
server).
Furthermore, this choice has an effect on behavior only during peak message
bursts—if application publishing overwhelms the quorum leader:
•
To favor maximum application publishing speed while accepting potential
message loss in the store, choose non-blocking send.
266
| Chapter 15
•
To favor minimum message loss in the store while throttling application
publishing speed, choose blocking send.
Publisher Mode 267
|
Publisher Mode
When an endpoint uses a store, its publisher send calls communicate outbound
messages to the store, as well as to the endpoint’s regular transports. Depending
upon application requirements, the publisher send call can also wait for the store
to confirm that it has received and stored each message. Different sequences of
these subtask elements produce different qualities of service.
Administrators must select the publisher mode that best suits the application’s
needs.
Table 73 Store Publisher Modes
Publisher Mode
Description
Store – Send – No Confirm
Highest throughput. Minimal message latency. More robust
delivery than regular reliability.
1. Send the message to the store. Do not wait for confirmation.
2. Send the message on the endpoint’s transports.
Store – Confirm – Send
Guarantees delivery in exchange for lower throughput and higher
message latency.
If the send call succeeds, then the store guarantees that all durable
subscribers will eventually receive the message. Conversely, if the
store operation fails, the send call also fails, and subscribers do not
receive the message through direct transports, nor from the store.
1. Send the message to the store.
2. Wait for the cluster to confirm storage.
3. Send the message on the endpoint’s transports.
268
| Chapter 15
Durable Behavior
Administrators configure the behavior of a durable and its interaction with
durable subscriber. This section presents the behavior choices you can specify. For
the configuration interface, see Configuring a Durable Definition, page 277.
Shared or Non-Shared
A non-shared durable represents exactly one durable subscriber. It supports
delivery assurance for that durable subscriber.
A shared durable represents a set of cooperating durable subscribers. It supports
apportioning the message stream among those durable subscribers.
Acknowledgement Mode
Durable subscribers acknowledge each message as they process it. However, the
client library can transmit acknowledgements to the cluster in either of two
modes—synchronous or asynchronous.
Table 74 Acknowledgement Mode
Mode
Description
Synchronous
Each time the application program acknowledges a message, the client library
immediately communicates the acknowledgement to the cluster, and waits for the
cluster to confirm that it has safely recorded that acknowledgement.
Asynchronous
The client library gathers batches of acknowledgements, and communicates the
batches to the cluster. (The application does not receive confirmation that the
cluster has safely recorded the batch of acknowledgements.)
In some situations, batching can improve throughput and latency performance.
However, after application failover, durable subscribers could receive duplicate
delivery of messages that they have already acknowledged (because the cluster
never received the most recent batch of acknowledgements).
Note that acknowledgement mode as described here is orthogonal to the
developer’s choice between automatic acknowledgement versus an explicit
acknowledge call.
Durable Behavior 269
|
Message Interest
A store collects all the messages from its publishers—but a subscriber might
require only a subset of those messages, and different subscribers might require
different subsets. (Developers and administrators must coordinate to configure
this behavior.)
Table 75 Message Interest
Behavior
Description
Store All
Messages
Durable subscribers require delivery of all messages in the store. Each durable
presents the entire message stream to its durable subscriber.
The subscriber create call must not specify any content matcher.
Store Matching
Messages
Durable subscribers require only a subset of messages in the store—that is, only
those messages that match a content matcher. Each durable presents only that
subset to its durable subscriber.
We recommend that the subscriber create call not specify any content matcher; the
resulting subscriber automatically uses the matcher from the durable definition.
(If the subscriber create call does specify a content matcher, it must be identical to
that of the durable definition.)
See Also
Message Interest, page 279
Durable Coordination Form, page 320
Content Matchers in TIBCO FTL Development
Changing Message Interest or Matcher Fields
From the moment that a subscriber object first interacts with a durable, you may
no longer change a durable’s message interest, nor its matcher fields. If these
configuration values must subsequently change, you can instead map the
subscriber to a new durable with the correct message interest and matcher fields.
See Also
Message Interest, page 279
Matcher Fields, page 279
270
| Chapter 15
Configuring the Realm Persistence Cluster
Administrators begin by defining the cluster (at most one per realm). The cluster
definition consists of servers and stores.
For background information, see Persistence Servers and Cluster on page 260.
For consequences of modifying this configuration, see Store and Durable
Modifications on page 118, and Quorum Behaviors on page 261.
Configuring the Realm Persistence Cluster 271
|
Cluster Heartbeat and Timeout Settings
Advanced settings on the cluster page let you adjust the heartbeat and timeout
parameters, which detect persistence server availability. We recommend using the
default values, except to resolve specific issues or as directed by TIBCO
personnel.
Table 76 Persistence Cluster Advanced Parameters
Parameter
Description
Client—Persistence Server
Heartbeat
The leader persistence server sends heartbeats to its
clients at this interval (in seconds).
Client—Persistence Server
Timeout
When the leader’s heartbeat is silent for this interval (in
seconds), its clients seek to connect to a new leader (from
among the other servers in the cluster.
Persistence Server—Persistence Server
Heartbeat
Store servers in the cluster exchange heartbeats at this
interval (in seconds).
Persistence Server—Persistence Server
Timeout
When the heartbeat of any server in the cluster is silent
for this interval (in seconds), the remaining servers
attempt to form a new quorum.
272
| Chapter 15
Configuring a Persistence Server Definition
The Persistence Server definition page presents the details of a server definition,
and lets you modify the definition.
For background information, see Persistence Servers and Cluster on page 260.
Modifications on page 118.
Configuring a Persistence Server Definition 273
|
Table 77 Persistence Server Parameters (Sheet 1 of 2)
Parameter
Description
Name
Required.
Name of the server.
Server names must be globally unique within the realm.
Description
Optional.
You can use this text field as a comment to describe the server and attach
administrative notes.
Weight
Required.
This value must be an integer in the range [1,10]. Larger values indicate greater
preference that the server becomes the leader.
Cluster Transport & Client Transports
For background information, see Persistence Server Transports on page 265.
Transport Type
Select one of the available transport types.
274
| Chapter 15
Table 77 Persistence Server Parameters (Sheet 2 of 2)
Parameter
Description
other transport
parameters
Supply the other transport parameters as needed. The set of parameters depends
on the transport type. In general, only a subset of parameters for the transport
type are available—FTL automatically supplies values for the remainder.
For transport parameter details, see Chapter 4, Transports, on page 35.
See also Client Transport and Non-Blocking Send on page 265.
Alternate
Client
Transport
Optional.
To define an alternate client transport, supply its transport type, parameters, and
a set of associated client host names. Clients on those specific host computers
communicate with this persistence server using the alternate transport. All other
clients use the regular client transport.
For background information, see Alternate Client Transport on page 265.
Configuring a Store Definition 275
|
Configuring a Store Definition
The Store definition page presents the details of a store definition, and lets you
modify the definition.
276
| Chapter 15
Table 78 Store Definition—Components
Parameter
Description
Name
Required.
Name of the store.
Store names must be unique within the cluster.
All names are limited to maximum length of 256 characters.
Description
Optional.
You can use this text field as a comment to describe the store and attach
Publisher Mode
This parameter governs communication among publisher send calls, the
store, and the endpoint’s regular transports—producing different qualities of
service. For complete details, see Publisher Mode on page 267.
Byte Limit
This parameter limits the volume of message data in the store. If publishing
another message would exceed this limit, the store rejects that message.
Zero is a special value, indicating no limit. The store may grow until it
exhausts available memory on any one of its servers.
Replicated
When enabled (default value), tibstore replicates the store across servers in
the cluster.
When disabled, tibstore does not replicate the store—only one server holds
the store’s data.
Durables
Each store defines a set of durables, which track the distribution of messages
to durable subscribers. To configure individual durables, see Configuring a
Durable Definition on page 277.
For background information, see and Durable Behavior on page 268.
Configuring a Durable Definition 277
|
Configuring a Durable Definition
The Durable definition page presents the details of a durable definition, and lets
you modify the definition.
For background information, see Durable Behavior on page 268.
278
| Chapter 15
Table 79 Durable Definition—Components (Sheet 1 of 2)
Parameter
Description
Name
Required.
Name of the durable.
Durable names must be unique within each store.
All names are limited to maximum length of 256 characters.
Description
Optional.
You can use this text field as a comment to describe the durable and attach
Shared
When disabled (default value), the durable retains a message stream for
exactly one durable subscriber.
When enabled, many subscribers can share this durable, which distributes
each message to only one of those subscribers.
Prefetch
Applies only to shared durables.
When a subscriber is ready, the store delivers a portion of the message
stream. This value (a positive integer) limits the number of messages in a
portion.
You can tune this parameter empirically to improve message throughput. If
some subscribers are idle while others are overloaded, try decreasing this
value. If the durable has a large message backlog, yet subscribers could
process more messages, try increasing this value.
Acknowledgement
Mode
When a subscriber finishes processing a message, the client library sends an
acknowledgement to the durable. This interaction can be either Synchronous
or Asynchronous. For complete details, see Acknowledgement Mode on
page 268.
Batch Time
In asynchronous acknowledgement mode, each client immediately sends
accumulated acknowledgements when the oldest acknowledgement has
waited for this interval (in seconds)—even before exceeding Batch Count.
Batch Count
In asynchronous acknowledgement mode, each client immediately sends
accumulated acknowledgements when the number of waiting
acknowledgements exceeds this number—even if Batch Time has not
elapsed.
Configuring a Durable Definition 279
|
Table 79 Durable Definition—Components (Sheet 2 of 2)
Parameter
Description
Message Interest
Message interest determines a stream of messages:
•
Store All Messages
indicates the full message stream that the store
collects.
•
Store Matching Messages
matcher (see Matcher
indicates a subset determined by a content
below).
Fields,
For complete details, see Message Interest on page 269.
Matcher Fields
Required when Message
Interest
is Store
Matching Messages.
(Developers and administrators coordinate to determine the appropriate
behavior; see Durable Coordination Form on page 320.)
For complete details, see Message Interest on page 269.
280
| Chapter 15
Configuring Persistence Stores within the Application Definition
Administrators can associate each application endpoint with at most one store.
That store serves all publisher and subscriber instances of the endpoint, in all
process instances of the application.
One store can serve several endpoints—either within one application program, or
across several application programs. For example, in the sample applications, one
store would serve the endpoints tibsend-endpoint and tibrecv-endpoint,
connecting the publisher in tibsend with the subscriber in and tibrecv.
Separate stores can serve separate endpoints of the same application.
See Also
Configuring an Application Definition, page 123
Stores for Delivery Assurance, page 253
Configuring Durable Subscribers within an Application Instance 281
|
Configuring Durable Subscribers within an Application Instance
When developing new applications that use stores and durables, application
developers and administrators coordinate to determine a list of subscriber names.
•
Each application process supplies a unique subscriber name in each create
subscriber call. This subscriber name represents the application process’ view
of its durable.
•
Administrators map each subscriber name to a durable name—that is, to a
durable as defined within the store. Administrators configure this mapping
on the application instance page.
The subscriber name and the durable name may be either identical strings or
different strings. For administrative simplicity, we recommend using identical
strings if possible. (In the image below, the example illustrates best practice;
administrators may veer from best practice when necessary.)
See Also
Configuring an Application Instance, page 127
Matching Instances for Subscriber Name Mapping
Matching Instances on page 25 describes the matching algorithm that the realm
server uses to determine the instance connections between endpoints (publisher
and subscriber objects) and the transports that implement them.
After a first pass determines those instance connections for transports, a second
pass (using the identical algorithm) determines the mapping from subscriber
names to durables.
282
| Chapter 15
Because the two passes are independent, you can configure the subscriber name
mapping independently from instance connections—in separate application
instance definitions. For example, you could key instance connections to the Host,
and key the subscriber name mapping to the Identifier.
We recommend that you use this independence to reduce the number of
application instance definitions.
Configuring a Default Durable
To configure the default durable on an endpoint, supply _default as the
subscriber name. The durable name can be any durable you have defined in the
store.
See Also
For background information, see Default Durable, page 258.
Persistence Servers Monitoring Summary 283
|
Persistence Servers Monitoring Summary
The Persistence Servers summary page lists the servers configured in the cluster.
Table 80 Persistence Servers Summary—Components
Column
Description
Status Icon
Icon representing the status of the persistence server process; see Table 81,
below.
Name
Name of the persistence server process.
Host
The hostname string of the persistence server’s host computer (if available).
ID
Client ID of the persistence server process (as a client of the realm server).
History
History indicates whether servers are up-to-date.
The first value is the server’s quorum number; see Current Quorum Number
on page 287, above.
The second value is the data state of the server. Higher values indicate more
recent data.
A history value of 0,0 indicates an empty server.
When the cluster does not contain enough up-to-date servers to form a
quorum, administrators may force a quorum, using the most up-to-date
server; see Forcing a Quorum on page 284.
284
| Chapter 15
Table 81 Persistence Server Status
Icon
Status
Running
Needs Restart
Out of Sync
Timed Out
Offline
Exception
Forming Quorum
Replica
Leader
Manual Intervention
Forcing a Quorum
When the cluster contains enough reachable servers, but not enough non-empty
servers to form a quorum, an administrator may force a quorum.
Before forcing a quorum, first verify that it is safe to do so:
1. Determine the process status of each unreachable server.
2. If none of the unreachable servers are running, it is safe to force a quorum.
Persistence Servers Monitoring Summary 285
|
3. If any server processes are running but unreachable (for example, because of a
network partition problem), then it is not safe to force a quorum. Those servers
could contain more recent message data than the quorum candidates, and
forcing a quorum would forfeit those messages. Instead, restore reachability
by repairing the network problem; then the quorum can reform itself without
administrator intervention.
Do not rely on server history state to determine whether it is safe to force a
quorum. History state information (which appears in the monitoring interface
and in persistence server log output) is not accurate enough for this purpose.
Example 4 Store Servers—Forcing a Quorum
Figure 33 monitors the state of a cluster that defines three servers. Only two
servers are reachable. The third server is unreachable.
Figure 33 Store Servers—Forcing a Quorum
The two reachable servers cannot form a quorum because server-2 is empty (see
Quorum Conditions—General Rule on page 260). If the administrator determines
that server-3 has exited, then it is safe to force a quorum. The administrator can
explicitly force a quorum by clicking the lightning bolt button (see Figure 33).
If, on the other hand, server-3 is still running, it could hold a more recent history
state than server-1 (the candidate with the most recent history state). Instead of
forcing a quorum, the administrator should endeavor to repair the network
problem that partitions server-3 from the other candidates.
See Also
Force Quorum on page 262.
286
| Chapter 15
Monitoring a Persistence Server
The Persistence Server monitoring page presents the status and properties of a
specific server. It also presents server monitoring statistics.
Table 82 Persistence Server Status—Components (Sheet 1 of 3)
Item
Description
Client ID
Client ID of the persistence server process (as a client of the realm server).
Administrators could use this client ID in a script to retrieve client
monitoring statistics about the persistence server from the realm server.
Monitoring a Persistence Server 287
|
Item
Description
Status
Status of the persistence server process (as a string).
Description
Description string (from the server definition page).
Quorum Status
If the server is running, this string indicates its status with respect to the
quorum.
Current Quorum
Number
Each time the servers form a quorum, they advance the quorum counter and
each participating server caches its value.
A lower value than other servers could indicate missing data.
History
History indicates whether servers are up-to-date.
The first value is the server’s quorum number; see Current
above.
Quorum Number,
The second value is the data state of the server. Higher values indicate more
recent data.
When the cluster does not contain enough up-to-date servers to form a
quorum, administrators may force a quorum, using the most up-to-date
server.
Force Timestamp
Zero indicates that the cluster formed a quorum in the usual way.
A timestamp indicates that the administrator forced a quorum at that time.
Last Contact
Time of the most recent contact between the realm server and this persistence
server.
Time Since Last
Contact
Approximate elapsed time since the most recent contact between the realm
server and this persistence server.
Realm Revision
Revision number of the realm definition received at the persistence server.
If this number is not equal to the realm server’s revision, then the persistence
server is not synchronized with the realm server, and might need to restart.
Startup Time
Timestamp when the persistence server first contacted the realm server.
Host Name
The hostname string of the persistence server’s host computer (if available).
IP Address
IP address of the persistence server’s host computer.
288
| Chapter 15
Item
Description
Other Info
Additional information about the persistence server; for example, hardware,
operating system, process ID.
Notices
Notes about persistence server status (as a realm server client).
Persistence Server Statistics
This monitoring page includes two kinds of statistics:
•
Statistics about the persistence server’s cluster transports and client
transports.
For details about transport statistics, see Catalog of Client Statistics on
page 184. For background information about cluster and client transports, see
Persistence Server Transports on page 265.
•
Statistics about the stores within this server (see Table 83, below).
(The sample interval for persistence server statistics is separate from the
sample interval for client monitoring. Administrators cannot modify it.)
Table 83 Store Statistics
Statistic Type
Descriptions
Tracking
Message Count
For each store in the server, a counter of this type tracks the
number of messages in the store at the close of the sample
interval.
Per store
For each store in the server, a counter of this type tracks the
storage (in bytes) that messages occupy in the store at the
close of the sample interval.
Per store
Message Size
Instantaneous
Instantaneous
Persistence Stores Monitoring Summary 289
|
Persistence Stores Monitoring Summary
The Persistence Stores summary page lists the stores in the cluster.
Table 84 Stores Summary—Components
Column
Description
Name
Name of the persistence store.
Messages
Number of messages in the store.
Bytes
Size (in bytes) that the messages occupy in the store.
Purge the store. (This action deletes all messages in the store.)
290
| Chapter 15
Monitoring a Store
The Persistence Store Status pane presents the status and properties of a specific
store.
Table 85 Persistence Store Status—Components
Item
Description
Name
Name of the store
Leader
Persistence server that is currently the quorum leader for this store.
Message Count
Number of messages in the store.
Message Size
Durables
The Durables summary pane lists the durables in the store.
Monitoring a Store 291
|
Table 86 Durable Subscribers Summary—Components
Column
Description
Name
Name of the durable (within the store).
Messages
Number of messages held in this durable.
Bytes
Client
For a non-shared durable, this column identifies the client process that
contains the subscriber object currently associated with the durable. To view
the client’s monitoring page, click this link.
For a shared durable, this column displays the number of clients with
subscribers on the durable. To view the shared durable’s monitoring page,
click this link.
Purge the durable. (This action deletes all messages in the durable.)
292
| Chapter 15
Monitoring a Shared Durable
The Shared Durable Status pane presents the status of a specific shared durable.
Table 87 Durable Status—Components
Item
Description
Name
Name of the shared durable.
Message Count
Number of unacknowledged messages in the shared durable.
Message Size
Size (in bytes) of unacknowledged messages.
Shared Durable Subscribers
The Shared Durable Subscribers pane displays recent operating details of the
subscribers that share a durable.
Monitoring a Shared Durable 293
|
Table 88 Shared Durable Status—Components
Item
Description
Each row represents one subscriber object sharing the durable.
Client ID
The subscriber object is in this client.
Last
Acknowledged
Approximate elapsed time since the subscriber acknowledged a message.
Last Dispatched
Approximate elapsed time since the client dispatched a message for the
subscriber (from an event queue).
Last Sent
Approximate elapsed time since the store server sent a batch of messages to
the subscriber.
Pending Messages
Number of messages sent to this client subscriber that remain
unacknowledged.
294
| Chapter 15
Starting a Persistence Server
1. Configure persistence using the realm server interface.
2. If a state file exists, check that it is current. If it is stale, remove it.
For more information, see Saving and Loading Persistence State on page 298,
and Restarting a Persistence Server with Saved State on page 299.
3. Start the server on its host computer using its command line (see tibstore
Command Line on page 295) or using your own start script.
Stopping a Persistence Server
To stop an individual persistence server, terminate the process.
To confirm the server’s new status, use the realm server interface (see Persistence
Servers Monitoring Summary on page 283 and Monitoring a Persistence Server
on page 286).
See Also
Suspending the Persistence Cluster, page 298
tibstore Command Line 295
|
tibstore Command Line
tibstore is an executable component that implements the persistence store
server. Administrators use the tibstore command line executable to start
tibstore server processes.
The command line parser accepts either form.
Before starting the tibstore executable, you must ensure that the library path
environment variable includes the FTL product installation bin directory.
Table 89 tibstore Command Line Parameters (Sheet 1 of 3)
Parameter
Arguments
Description
Display a help message describing the command
line parameters and options.
--help
-h
Realm
--name
server_name
Set the name of this tibstore server. The
server_name must match one of the names defined in
the cluster. Each server process must use a distinct
name.
-n
--realmserver
Required.
URL
Required.
URL of the realm server.
-rs
The tibstore server contacts the realm server at
this location to receive its realm definition. Supply
the location of the primary realm server or a
satellite server (see Connect Port on page 86).
-s
URL
Optional.
URL of the backup realm server.
If the regular realm server is unavailable, the
tibstore server contacts the backup realm server
at this location to receive its realm definition.
Supply the location of the backup realm server (see
Connect Port on page 86).
296
| Chapter 15
Parameter
Arguments
Description
path
Optional.
Working Storage
--data
When present, the tibstore server stores its
working data files in this path location. (The
directory at path must exist; the tibstore server
does not create it automatically.)
-d
directory.
Ensure that each tibstore server process uses a
unique path location.
(The tibstore server stores quorum data in this
directory. It does not store messages or
acknowledgements here.)
State File
See also, Saving and Loading Persistence State on page 298.
--savedir
path
Optional.
When present, the tibstore server writes its state
file in this path location. (The directory at path must
exist; the tibstore server does not create it
automatically.)
directory.
The state file name is always server_name.state.
A server writes it state file only in response to a
Save command from the Persistence Servers
Management page in the realm server GUI. This
parameter specifies the location, but does not
trigger a save operation.
This parameter does not affect loading a state file.
For more information, see Saving the State of a
Persistence Server on page 298.
tibstore Command Line 297
|
Parameter
Arguments
Description
--load
path
Optional.
When present, the tibstore server loads its state
from this state file. (Specify the file pathname, not
only the directory path.)
When absent, the server loads its state from the
default state file, server_name.state.
For more information, see Restarting a Persistence
Server with Saved State on page 299.
Security
--password-file
path
Optional. (Required for JAAS authentication.)
When present, the tibstore server reads a
username and password from the file at path, and
authenticates itself to the realm server using those
credentials. For details, see Password File on
page 83.
-pf
Logging
--trace
-t
level
Optional.
When present, the tibstore server outputs trace
messages to stderr. You may specify any of the
standard log level strings (see Log Levels in the
book TIBCO FTL Development).
When absent, the default trace level is info.
298
| Chapter 15
Saving and Loading Persistence State
The persistence GUI includes a facility to save the content of a server’s stores to a
file. When a server starts, it can load its initial state from that file. You can use this
facility to migrate the persistence cluster to a new physical location, or for nightly
backups.
Task K Suspending the Persistence Cluster
Suspending the cluster is a prerequisite subtask to saving its servers’ state. You
can suspend all the servers in the persistence cluster (however, you cannot
suspend a server individually).
1. In the realm server GUI, view the Persistence Servers monitoring summary
page.
2. Click the wrench icon at the top right of the page, to view the Persistence
Servers Management page.
If JAAS is enabled, you must be in the ftl-admin authorization group to do
this step.
3. Click the Suspend Cluster button. Click Yes to confirm this operation.
4. Wait until all the servers are suspended.
To verify suspension, either check the icon in the Status column or check the
server log messages.
A suspended server is still an active process. However, a suspended server does
not communicate with clients, nor with other servers. Its only available operation
is to save its state to a file.
After a server process is suspended, it cannot resume normal communication
with clients nor with other servers. To return to normal operation, you must stop
the server process, and then restart it.
Task L Saving the State of a Persistence Server
Prerequisite: All the servers in the cluster must be suspended.
5. On the Persistence Servers Management page, select the server or servers to
save.
You may save all the servers, or only a subset. The choice depends on
available disk space, network speed and bandwidth. If you save only a subset,
Saving and Loading Persistence State 299
|
we recommend saving the quorum leader or the server with the latest history
numbers.
6. Click the Save Selected button. Click Yes to confirm this operation.
7. Wait for the servers to finish saving.
To verify the save operation, check both the icon in the Save Status column,
and the server log messages.
If a save operation fails (for example, the disk is full), take corrective action
and save again.
.
The save operation includes only replicated state. If replication is not enabled
for a store, then the save operation excludes the content of that store from the
state file.
The state file name is server_name.state.
For more information, see State File on page 296.
If the state file already exists, the save operation renames it to
server_name.state.backup before writing a new state file.
8. Stop the server processes.
Task M Restarting a Persistence Server with Saved State
9. Determine which state file or files to load. If needed, copy state files.
If you saved the state of all the servers, then each one can load its own state
file.
If you saved a subset of the servers, you could select one state file and arrange
for all the servers to load it.
10. Start the servers. If needed, supply the --load parameter.
If the --load parameter specifies a state file, and the server finds that state
file, then it loads its initial state from that file. If it cannot load that state file,
then the server logs an error and starts with empty state.
If the --load parameter is absent, then server automatically searches for the
default state file in the current directory. If the server finds the default state
file, then it loads its initial state from that file; otherwise, the server starts with
empty state.
11. Verify cluster functionality by checking the icons in the Status column, and
checking the server log messages.
300
| Chapter 15
Persistence functionality resumes when the servers can form a quorum. For
details, see Quorum Conditions—General Rule on page 260.
Purging Durables or Stores 301
|
Purging Durables or Stores
You can use the monitoring interface to purge all stored messages from an
individual durable, or from an entire persistence store (that is, from all its
durables).
Purging does not require locking the realm definition. It does require
administrative authorization.
Purging a Durable
1. From the home page, navigate to the Persistence Stores Monitoring Summary.
2. Navigate to the individual store by clicking its name (or its view arrow) in the
summary table; see Durables on page 290.
3. Locate the durable to purge within the durables table, and click its purge icon.
4. Confirm.
This action deletes all messages in the durable. You cannot undo a purge
operation.
Purging a Store
1. From the home page, navigate to the Persistence Stores Monitoring Summary.
2. Locate the store to purge within the summary table, and click its purge icon.
3. Confirm.
This action deletes all messages in the store. You cannot undo a purge
operation.
302
| Chapter 15
| 303
Chapter 16
Package Contents
This chapter describes the contents of the installed product.
Topics
•
Directory Structure, page 304
•
Sample Programs, page 305
304
| Chapter 16
Package Contents
Directory Structure
The FTL installation directory contains the subdirectories in Table 90.
Table 90 FTL Directories
Directory
Description
bin
FTL library DLL files (for Windows).
Scripts to run the realm server and its administration utility.
Python scripts and library.
Rendezvous adapter executable.
Transport bridge executable.
Store server executable.
Realm server .jar file.
Jetty web server .jar file.
include
C API header files (in subdirectories).
lib
FTL library files (for UNIX) and .jar files.
samples
Sample programs. For more detail, see Sample Programs on page 305.
Sample Programs 305
|
Sample Programs
The samples directory contains the files in Table 91 and the subdirectories in
Table 92.
Table 93 on page 306 describes some of the sample programs, however, the list is
not exhaustive. For descriptions of other sample programs, see the readme files in
each directory.
Table 91 Files in Samples Directory
Directory
Description
readme.txt
Instructions to compile and run sample programs.
setup
Script that defines environment variables (such as PATH, LD_LIBRARY_PATH and
CLASSPATH) for the samples. We recommend that all programmers start with this
script.
Table 92 Samples Directories
Directory
Description
bin
Executable sample programs, precompiled from C sources.
scripts
Sample scripts to start and stop the realm server. You must start the realm server
with this script before running the sample programs.
Sample script to start the Rendezvous adapter.
Sample configuration files for the realm server and Rendezvous adapter.
The file readme.txt contains instructions for using these samples.
src
Sample program source code in C, Java and .NET. You may use these samples as
models for your application programs.
The file readme.txt contains instructions for compiling.
jaas
Files that configure JAAS authentication and authorization for the sample scripts.
To use JAAS with the samples, supply the -jaas flag to the sample scripts.
config
More sample configuration files, for use as instructional models, but not related to
the sample programs.
306
| Chapter 16
Package Contents
Table 93 Sample Programs
Programs
Description
Each sample program prints a usage summary in response to the -h command line option.
One-to-Many Communication
tibrecv
tibrecv
creates a subscriber and outputs the messages it receives.
Start this program first.
tibsend
tibsend
publishes messages for tibrecv.
One-to-One Communication
tibreply
tibreply
creates a subscriber, and replies to request messages it receives.
Start this program first.
tibrequest
tibrequest creates an inbox subscriber, sends request messages to tibreply, and
receives replies at its inbox.
| 307
Appendix A
Coordination Forms
This appendix contains forms that help developers and administrators coordinate
application details.
Topics
•
Application Coordination Form, page 308
•
Endpoint Coordination Form, page 311
•
Format Coordination Form, page 315
•
308
| Appendix A
Coordination Forms
Application Coordination Form
Developers and administrators can use the form in this section to coordinate the
details of an application and its requirements.
Table 94 Application Coordination Form
Identification
Application Name
(Project Title)
Version and Date
Executable File
Names
Developer
Name(s)
Administrator
Name(s)
General
Application
Description
Communicates
with these Other
Applications
Requires Dynamic
Formats?
(Explain)
Requires Low
Latency? (Explain)
Inline Event Queues (List Endpoints and Explain Requirement)
Application Coordination Form 309
|
Number of dispatch threads in application program code
Requires stores and durables?
(If so, complete the Store and Durable Coordination Form.)
Expected Deployment
Realm Name
Realm Server Locations (Define the runtime mechanism that the application uses to obtain the
location of its regular and backup realm servers; for example: command line parameters,
configuration file parameters, environment variables.)
Number of Process Instances (approximate):
Do these processes use the group facility?
Group name:
Hardware
Network
Part of an Application Suite with other Applications?
Specific Start Order within the Suite?
Differential Treatment of Processes (based on hostname or identifier)
Application Instance Identifier (for example: command line parameter, configuration file parameter,
environment variable)
310
| Appendix A
Coordination Forms
Endpoint Coordination Form 311
|
Endpoint Coordination Form
details that enable effective and efficient data transmission among application
programs. It captures specific details about each endpoint ability, including a brief
description of the messages that each ability carries, the expected volume of data
in each ability, and the priority of the data (relative to other messages).
Administrators use these details to select appropriate host computers and
transports.
Table 95 Endpoint Coordination Form
Description of Messages
Urgent
Volume
Endpoint Name:
Related Endpoints:
Subscriber
Inbox Subscriber
Send
Send to Inbox
Process (PROC) transport needed: Yes | No (choose one).
Largest outbound message size (in bytes): Send ____. Send to Inbox ____.
For send abilities, configure either Backlog Buffer Size _____ or Blocking Send (choose one).
312
| Appendix A
Coordination Forms
Urgent
Volume
Endpoint Name:
Related Endpoints:
Subscriber
Inbox Subscriber
Send
Send to Inbox
Endpoint Name:
Related Endpoints:
Subscriber
Inbox Subscriber
Send
Send to Inbox
Endpoint Coordination Form 313
|
Urgent
Volume
Endpoint Name:
Related Endpoints:
Subscriber
Inbox Subscriber
Send
Send to Inbox
Endpoint Name:
Related Endpoints:
Subscriber
Inbox Subscriber
Send
Send to Inbox
314
| Appendix A
Coordination Forms
Urgent
Volume
Endpoint Name:
Related Endpoints:
Subscriber
Inbox Subscriber
Send
Send to Inbox
Format Coordination Form 315
|
Format Coordination Form
Table 96 Format Coordination Form
details of message formats for an application. It captures specific details about
each format.
Field Name
Datatype
Format Name:
Field 1
Field 2
Field 3
Field 4
Field 5
Field 6
Field 7
Field 8
Field 9
Field 10
316
| Appendix A
Coordination Forms
Field Name
Format Name:
Field 1
Field 2
Field 3
Field 4
Field 5
Field 6
Field 7
Field 8
Field 9
Field 10
Format Name:
Field 1
Field 2
Field 3
Field 4
Field 5
Field 6
Field 7
Field 8
Field 9
Field 10
Datatype
|
Field Name
Datatype
Format Name:
Field 1
Field 2
Field 3
Field 4
Field 5
Field 6
Field 7
Field 8
Field 9
Field 10
Format Name:
Field 1
Field 2
Field 3
Field 4
Field 5
Field 6
Field 7
Field 8
Field 9
Field 10
318
| Appendix A
Coordination Forms
Field Name
Format Name:
Field 1
Field 2
Field 3
Field 4
Field 5
Field 6
Field 7
Field 8
Field 9
Field 10
Format Name:
Field 1
Field 2
Field 3
Field 4
Field 5
Field 6
Field 7
Field 8
Field 9
Field 10
Datatype
|
Field Name
Datatype
Format Name:
Field 1
Field 2
Field 3
Field 4
Field 5
Field 6
Field 7
Field 8
Field 9
Field 10
320
| Appendix A
Coordination Forms
Durable Coordination Form
Table 97 Durable Coordination Form
details of durables.
Durable Subscribers
Subscriber
Endpoint
Goal of Durable
Delivery Assurance _______ or Apportioning Message Stream _______
Publisher
Related Endpoints
List the publisher endpoints from which these durable subscribers
require messages.
Durable
Subscriber Names
List the durable subscriber names on this endpoint.
Content Matcher
If these durable subscribers use a content matcher, specify it here.
Otherwise, indicate None.
Durable Coordination Form 321
|
Subscriber
Endpoint
Goal of Durable
Publisher
Related Endpoints
List the publish endpoints from which these durable subscribers require
messages.
Durable
Subscriber Names
Content Matcher
Subscriber
Endpoint
Goal of Durable
Publisher
Related Endpoints
messages.
Durable
Subscriber Names
Content Matcher
322
| Appendix A
Coordination Forms
Subscriber
Endpoint
Goal of Durable
Publisher
Related Endpoints
messages.
Durable
Subscriber Names
Content Matcher
Upgrade Migration to a New Release 323
|
Appendix B
Upgrade Migration to a New Release
To upgrade from an earlier release of TIBCO FTL, read this appendix first.
Topics
•
Upgrading Realm Servers, page 324
•
Upgrading tibstore Servers, page 325
324
| Appendix B
Upgrading Realm Servers
The realm server maintains its database state on the file system. This stored
database enables straightforward migration to new releases.
Old and new realm servers can coexist during upgrade migration, which enables
continuous service.
Task N Upgrading a Set of Affiliated Realm Servers
Upgrade each individual realm server. We recommend this order:
1. Primary
2. Primary’s backup
3. Each satellite and then its backup
Task O Upgrading Each Individual Realm Server Process
1. Backup the realm server database.
See --backup_database on page 95 (or use your own custom script that calls
the tibrealmadmin utility with this command).
2. Stop the old realm server process.
See --shutdown on page 95 (or use your own custom script that calls the
utility with this command).
tibrealmadmin
3. Install the new realm server on the host computer—including executable files,
plus library and script support files. Install the full FTL product. See
instructions in TIBCO FTL Installation.
4. Start the new realm server process using the same command or script that you
had used for the old realm server.
The new realm server loads the existing realm database files, and is ready to
serve clients.
5. If the new realm server has satellites or a backup, wait sufficient time for those
processes to reestablish contact with the new realm server process.
6. If the new realm server has a backup, wait sufficient time for clients to migrate
from the backup to the new realm server. Then upgrade the backup realm
server.
See Also
Using the tibrealmserver Executable, page 85.
Using the tibrealmadmin Utility, page 94.
Upgrading tibstore Servers 325
|
Upgrading tibstore Servers
After upgrading the realm server and the tibstore cluster to release 4.1,
administrators may configure replication of stores that contain shared durables.
Task P Rolling Upgrade of tibstore from Release 4.0 to 4.1
The tibstore server executables of release 4.0 and 4.1 can cooperate in the same
cluster, so you can upgrade tibstore without a complete shutdown of the store
feature.
1. Upgrade Realm Servers Upgrade all realm servers to the new release; see
Upgrading Realm Servers on page 324.
2. Determine tibstore Server Upgrade Order Choose the order in which you will
upgrade the tibstore servers. First upgrade servers that are not the quorum
leader; you must upgrade the quorum leader process last.
3. Ensure the Cluster is Up-to-Date Use the monitoring GUI to verify that all the
servers in the cluster are running and up-to-date; see Persistence Servers
Monitoring Summary on page 283.
4. Stop one Server Process Stop one tibstore server processes. No special
utility commands are needed.
5. Clean Up Uninstall the old FTL installation package from that server’s host
computer. See instructions in TIBCO FTL Installation.
6. Install New Install the new release (the full FTL product) on that host
computer. See instructions in TIBCO FTL Installation.
7. Start the New Server Restart the upgraded tibstore server process on that
host computer.
8. Synchronize Data Wait for the new server to synchronize and join the quorum.
9. Repeat Repeat from step 3 until you have upgraded all the tibstore servers.
10. Upgrade Clients Ensure that all persistence clients use the latest client library.
11. Configure Replication Administrators may now configure replication of stores
that contain shared durables.
326
| Appendix B
FTL Processes as Windows Services 327
|
Appendix C
FTL Processes as Windows Services
You can arrange for realm servers, persistence servers and transport bridges to
run as Windows services.
Topics
•
Overview, page 328
•
Installing a Persistence Server as a Windows Service, page 329
•
Installing a Transport Bridge as a Windows Service, page 330
•
Installing the Realm Server as a Windows Service, page 331
•
Uninstalling a Windows Service, page 333
328
| Appendix C
Overview
To arrange Windows services, we recommend using the prunsrv tool, which is
part of the Apache Procrun package. The FTL installer includes this package on
Windows platforms. For documentation, see
http://commons.apache.org/proper/commons-daemon/procrun.html.
Prerequisite
Before arranging FTL processes as Windows services, ensure that both Java and
the FTL Windows package are installed on a local disk of the host computer (not
on a mapped network drive).
Installing a Persistence Server as a Windows Service 329
|
Installing a Persistence Server as a Windows Service
Model your command line on this template:
prunsrv.exe //IS/tibstore
--DisplayName="TIBCO FTL tibstore (pserver) Persistence Server"
--StartImage=TIBCO_HOME\ftl\version\bin\tibstore.exe
--LibraryPath=TIBCO_HOME\ftl\version\bin
--StartParams=-rs;realm_server_URL;--name;pserver_name
--DependsOn tibrealmserver
Notice these aspects of this command line template:
•
--StartImage
•
--LibraryPath
•
--StartParams contains the command line parameters for the tibstore
executable. Semicolon (;) is the separator character, as prunsrv does not allow
spaces.
•
--DependsOn
is the file path of the persistence server executable.
is the directory containing FTL DLL files.
indicates the realm server, specified by its name as a Windows
service.
330
| Appendix C
Installing a Transport Bridge as a Windows Service
prunsrv.exe //IS/tibbridge
--DisplayName="TIBCO FTL tibbridge Transport Bridge"
--StartImage=TIBCO_HOME\ftl\version\bin\tibbridge.exe
--StartParams=-rs;realm_server_URL;-n;bridge_name
--DependsOn tibrealmserver
•
--StartImage
•
--LibraryPath
•
contains the command line parameters for the tibbridge
executable. Semicolon (;) is the separator character, as prunsrv does not allow
spaces.
•
--DependsOn
is the directory containing FTL DLL files.
--StartParams
service.
is the file path of the transport bridge executable.
indicates the realm server, specified by its name as a Windows
Installing the Realm Server as a Windows Service 331
|
Installing the Realm Server as a Windows Service
prunsrv.exe //IS/tibrealmserver
--DisplayName="TIBCO FTL Realm Server"
--Install=TIBCO_HOME\ftl\version\bin\prunsrv.exe
--StartMode=java
--StopMode=java
--StartClass=com.tibco.ftl.realmserver.RealmServer
--StopClass=com.tibco.ftl.admin.RSAdmin
--StartParams=--http;localhost:port;
--StopParams=-rs;http://localhost:port;-x
--JavaHome=Java_folder
--Classpath=TIBCO_HOME\ftl\version\bin\realmserver.jar;TIBCO_HOME\
ftl\version\bin\jetty9-all.jar;TIBCO_HOME\ftl\version\bin\h2-1.3.159.
jar;TIBCO_HOME\ftl\version\lib\json_simple-1.1.jar;TIBCO_HOME\ftl\
version\lib\tibftl.jar
•
--Install
•
Specify --StartMode, --StopMode, --StartClass and --StopClass exactly
as shown in this template.
•
--StartParams contains the command line parameters for the realm server
executable (tibrealmserver). This template illustrates only the minimum
required parameter set. Semicolon (;) is the separator character, as prunsrv
does not allow spaces.
•
--StopParams contains the command line parameters for the realm server
administration utility (tibrealmadmin). This template illustrates the
command to shut down the realm server. Semicolon (;) is the separator
character, as prunsrv does not allow spaces.
is the file path of the prunsrv executable.
If you use JAAS for realm server security, then we do not recommend using
--StopParams.
Instead, stop the realm server using the tibrealmadmin utility.
Including credentials in the --StopParams would expose that sensitive
information, posing a security risk.
is the directory containing JDK 1.7.
•
--JavaHome
•
--LibraryPath
is the directory containing FTL JAR files.
332
| Appendix C
•
lists the JAR files that the realm server requires. You must
specify all of these files.
--Classpath
Uninstalling a Windows Service 333
|
Uninstalling a Windows Service
prunsrv.exe //DS/service_name
334
| Appendix C
| 335
Index
A
ability 4, 18, 19
connector 20
cover 21
grid 19
in diagrams 19
active deployment request panel, realm server
interface 170
adapter, see Rendezvous adapter
affiliated realm server 75
application 5
definition 6, 23
configuring 123
diagram 23
definitions, summary 122
instance 5
definition 6, 24
as solution 16
configuring 127
process instance 23
apportioning message streams 259
architecture 252
asymmetric multicast topology 42
authentication & authorization
realm server 82
Rendezvous adapter 197
transport bridge 83, 233
auto-save, realm server interface 99
B
backlog
send 47
transport configuration 133
backup realm server 75
blocking send 47
restriction with inline mode 48
bridge
definition page 242
status, monitoring 245
summary of definitions 241
summary, monitoring 244
transport 221
browsers, support for 98
built-in format 10, 13
bus, transports establish bus 36
C
client
disable 164
status, monitoring 161
summary, monitoring 160
client monitoring 181
sample interval 140
cluster, persistence 260
configuring 270
collision, durable subscriber 258
communication abilities 18
connect end, pair connection 44
connection
connection-oriented protocol 44
instance 26
graph 145
connector 20, 129
as abilities 16
example 30, 32
in diagrams 20
content matcher 3
contents of installed package 304
coordination forms 307
cover 21
336
| Index
customer support xxv
D
datatype, table of field types 137
default durable 258
configuring 282
default instance 25
delivery assurance 253
architecture 251
deploy
last request, realm server interface 173
realm server command 101
transaction 112
deployments, realm server interface 168
direct path requirement for non-shared durables 253,
257
direction, ability 18
directory tree structure 304
disable 164
durable
acknowledgement mode, durable subscriber 268
configuring 277
default 258
monitoring 290
durable subscriber
application configuration 263
collision 258
configuring 281
dynamic format 10
restricting 141
per application 125
per realm 140
dynamic TCP 60
dynamic update of realm definition 115
E
edit
transport, edit configuration manually 134
eFTL
configuring 121
monitoring 155
empty persistence server 260, 283
endpoint 4, 17
abilities 18
as requirement 16
implementing 17
in diagrams 19
endpoint connector 129
F
fault tolerance
configuring realm server and clients 80
group facility 215
persistence cluster 262
field 3
table of datatypes 137
filter, realm server interface 106
force quorum 261, 284
format 3
built-in 13
definition 6
definition, configuring 136
designing and defining 12
managed, dynamic and built-in 10
restricting 141
show historic versions 135
summary 135
forms, coordination 307
fragmentary transport 38
G
general rule, quorum formation conditions 260
Index 337
|
global scope 56
graph
instance connections 145
transport relationships 152
group facility 215
J
JAAS 82
samples 305
H
L
historic format versions 135
hub and spoke topology 41
I
icons
persistence server status 284
realm server browser interface 101
implement endpoint 17
inbound
direction 4
inbox 3
ability 19
init_bridge.py 238, 246
init_groups.py 218
inline mode 49
and blocking send, restriction 48
and receive spin limit 52
installed directories 304
instance 5
application instance definition 24
default vs. named 25
connections 26
graph 145
process 23
interest, subscriber 46
inter-thread (PROC) transport 72
last deployment request, realm server interface 173
leader, quorum 260, 260
length, maximum for names 108
listen end, pair connection 44
location of components 304
lock
lock & edit, realm server command 101
realm modification 111
loopback, multicast 67
M
manage all formats 141
application parameter 125
modification requires restart 115, 118
realm parameter 140
managed format 10
manual transport configuration 134
matching algorithm for application instances 25
persistence 281
maximum length 108
Mcast, see multicast transport
mesh
pair connection 41
topology 40
message 3
field types 137
message interest, store 269
model, realm configuration 16
modify realm definition 115
338
| Index
multicast
asymmetric topology 42
transport 64
multiple transports 28
N
name
reserved 108
named instance definition 25
non-blocking send 47
non-shared durables 253, 268
O
one-to-many and one-to-one communication 3
one-to-many and one-to-one, reach 18
opaque, built-in message format 13
options, realm server command line 84
outbound
direction 4
transports 265
server monitoring 286
shared durable, monitoring 292
store, monitoring status 290
stores, monitoring summary 289
preload formats 10, 126
priority 28
PROC transport (inter-thread) 72
process
instance, application 23
start order 44
properties
realm server command line options 84
realm, configuring 139
publisher 3
publisher mode, store 267
purge
client or satellite 103
durable 103, 291
durable or store 301
store 103, 289
Python scripts, realm configuration using 177
Q
P
package contents 303
pair connection 44
larger topologies 40
password file
persistence 251
configuring servers and stores 270
empty server 260, 283
fault tolerance 262
server
command line 295
purge 301
status and icons 284
summary 283
quorum 260
conditions to form, general rule 260
R
RDMA 57
reach, ability 18
realm 5
browsing using GUI tools 143
configuration model 16
configuring using GUI 121
configuring using Python scripts 177
deploy
restart client 115
Index 339
|
transaction 112
lock 111
monitoring 155
object 5
properties, configuring 139
Python scripts 177
requirements 27
server 5
administrative utility 94
affiliated, backup & satellite 75
authentication and authorization 82
browser URL 98
command line 85
disabling clients 164
icons 101
process 74
security 82
storage 110
terminology 6
receive
ability 19
direction 18
receive spin limit 133, 50
receive_inbox ability 19
redeploy, realm server command 174
refresh, realm server command 101
relationships, transport 38
graph 152
reliable multicast transport 64
reliable UDP transport 70
remote direct memory access (RDMA) 57
configuration 198
field datatype mapping 206
JAAS 197
message subject 205
request/reply interactions 209
subject
collision and validation 212
translation 205
tibrvadapter 196
XML configuration 198
request/reply interactions, Rendezvous adapter 209
require subscriber interest, multicast transport 65
requirements
direct path for non-shared durables 253, 257
realm 27
transports, unique 37
reserved names 108
restricting formats 141
restrictions
names 108
revert, realm server command 102
rs_script.py 179
RUDP transport 70
S
sample programs 305
satellite 75
configuring realm server and clients 81
monitoring summary 165
save, realm server command 102
security, realm server 82
send
ability 19
blocking vs. non-blocking 47
direction 18
send_inbox ability 19
serial communications 28
server, persistence 260
command line 295
configuring 272
server, realm, monitoring 157
setup script
group facility 218
shared durables 259, 268
configuring 278
shared memory transport 55
non-blocking send 47
shm, see shared memory transport
show historic formats 135
size units 109
start order, process 44
static TCP 62
340
| Index
statistics
client monitoring 181
persistence server 288
status, persistence server 284
store, persistence 253
associating with an application endpoint 280
configuring 275
message interest 269
publisher mode 267
subscriber 3
interest 46
subscriber name (durable), configuring 281
summary pages, realm server interface 106
support, contacting xxv
T
TCP
dynamic 60
static 62
technical support xxv
tibbridge (executable) 232
TIBCO_HOME xxii
tibrealmadmin, command line 94
tibrealmserver, command line 85
tibrvadapter, command line 196
tibstore command line 295
topology
bus 40
transport bridge 228
transport 4
abilities 18
as communications interface 36
definition 6
configuring 131
unitary and fragmentary 38
dynamic TCP 60
establish a bus 36
example 30, 32
implements endpoint 17
in diagrams 20
multicast 64
overview 36
persistence server 265
PROC 72
relationships 38
graph 152
remote direct memory access (RDMA) 57
roles 36
RUDP 70
shared memory 55
static TCP 62
summary of definitions 130
types 28
transport bridge 221
types, field 137
U
underscore character 108
unitary
mesh topology 40
transport definition 38
units 109
URL, realm server browser interface 98
V
validation results, realm server interface 144
volume 28
W
weight, persistence server 260
Index 341
|
X
XML, Rendezvous adapter configuration 198

TIBCO FTL Administration

Transcription

Similar documents

jrealm

TURN YOUR PANASONIC AG-AF101 or AG-AF100 INTO

GRUE TOUT-TERRAIN DE 1500 TONNES PRÈS DE LA CHUTE

London Bridge Redevelopment

TCPDF Example 021

LOCATIONS - London Bridge Hospital

Bridge Builder - First Baptist Church Wetumpka

DAOC3x_h for cd.qxd - Dark Age of Camelot

Defining Systematic Creativity in the Digital Realm