Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 2 TIBCO Hawk Component Configurations : Transport Mode Configuration

Transport Mode Configuration
Different transport modes are available to be configured as a means of communication between Hawk Agent and HMA, and Hawk Agent and Hawk Console, and they are:
TIBCO Hawk installation has TCP Transport for TIBCO Hawk configured as the default mode of message and event transport between Hawk Agent and AMI-based applications, as well as between Hawk Agent and Hawk Console.
If you choose TCP Transport for TIBCO Hawk as the transport between Hawk Agent and Console, you can use the same transport between Hawk Agent and AMI based application except HMA. For HMA, you can use TIBCO Rendezvous as transport and use TCP Transport for TIBCO Hawk and TIBCO Rendezvous Bridge for communicating with Hawk Agent.
If TIBCO Rendezvous is chosen as a transport between the Hawk Agent and the Hawk Console, the same is used a transport between the Hawk Agent and the HMA or other AMI based applications. You cannot configure it to use a different transport.
If you choose to use TIBCO Enterprise Message Service as the transport between the Hawk Agent and the Console, you can only use TIBCO Rendezvous as the transport between the Hawk Agent and the HMA or other AMI based applications.
The above combinations can be configured using various configuration files, as described in next few sections of this chapter.
TIBCO Rendezvous and TIBCO EMS are two independent products that need to be installed separately. Additional configurations need to be performed manually based on whether they are installed before or after installing TIBCO Hawk, and whether any of them share the same TIBCO_HOME installation folder.
A Single TIBCO_HOME Location for Various TIBCO Products
If you are using or planning to use a single TIBCO_HOME for all TIBCO Rendezvous, TIBCO EMS, and TIBCO Hawk components, read this section. Otherwise, you might skip to the section Different TIBCO_HOME Locations for Various TIBCO Products.
Using pre-installed and pre-configured existing transports
You can use an existing transport (TIBCO Rendezvous or TIBCO EMS) either from a previous installation of TIBCO Hawk or independent installations of these TIBCO products in the same TIBCO_HOME where Hawk is installed. Update all the TRA configuration files (for example, tibhawkagent.tra), script files (such as, starthawkconsole and starthma), Hawk Console configuration files with the correct locations of EMS_HOME and RV_HOME and the execution environment.
Setup all the required libraries and their paths during the post-install configuration step of the TIBCO Hawk installation.
Installing TIBCO Rendezvous or TIBCO EMS transports after installing TIBCO Hawk
If you install TIBCO Rendezvous or TIBCO Enterprise Message Service in the same TIBCO_HOME after TIBCO Hawk, ensure the following to set the correct runtime environment for the TIBCO Hawk components.
Edit and modify TRA configuration files (all the files with the extension ".tra" in CONFIG_FOLDER/bin) to set the correct installation location of TIBCO Rendezvous and TIBCO Enterprise Message Service. That is, set the correct values for tibco.env.EMS_HOME and tibco.env.RV_HOME environment variables in all the TRA configuration files.
On Unix or Linux, edit and modify the starthma.sh file with the correct RV_HOME location if TIBCO Rendezvous is installed after TIBCO Hawk.
Copy the following Java libraries for TIBCO Rendezvous as transport:
RV_HOME/lib/tibrvj.jar
Copy the following Java libraries for TIBCO EMS as transport:
EMS_HOME/lib/tibrvjms.jar
EMS_HOME/lib/tibjms.jar
EMS_HOME/lib/tibcrypt.jar
EMS_HOME/lib/jms-2.0.jar (in case of EMS 8.x)
To configure Hawk WebConsole runtime environment, assuming TIBCO Hawk is installed with default supplied Tomcat web server, edit and modify HAWK_HOME/webconsole/startwebconsole.bat and HAWK_HOME/webconsole/tomcat/bin/setenv.bat (.bat file on Windows, and .sh on Unix/Linux) to set RV_HOME and EMS_HOME correctly.
If you are not using EMS as transport, then it is recommended that you remove the EMS_HOME entries from startwebconsole.bat and setenv.bat (the .bat file on Windows, and the .sh file on UNIX/Linux) files, to avoid any issues with Hawk WebConsole start.
Different TIBCO_HOME Locations for Various TIBCO Products
If you are using or planning on using a different TIBCO_HOME for all TIBCO Rendezvous, TIBCO Enterprise Message Service, and TIBCO Hawk components, read this section. Otherwise, skip to the next section.
Since TIBCO_HOME for Hawk is different from that of TIBCO Rendezvous and TIBCO Enterprise Message Service, ensure that appropriate installation locations are updated as follows:
Edit and modify the TRA configuration files (all the files with extension ".tra" in CONFIG_FOLDER/bin) to set the correct installation location of TIBCO Rendezvous and TIBCO Enterprise Message Service. That is, set the correct values for tibco.env.EMS_HOME and tibco.env.RV_HOME environment variables in all the TRA configuration files.
On Unix/Linux, if TIBCO Rendezvous is installed at different TIBCO_HOME, then edit and modify the starthma.sh file with the correct RV_HOME location.
Copy the following Java libraries for TIBCO Rendezvous as transport:
RV_HOME/lib/tibrvj.jar
Copy the following Java libraries for TIBCO EMS as transport:
EMS_HOME/lib/tibrvjms.jar
EMS_HOME/lib/tibjms.jar
EMS_HOME/lib/tibcrypt.jar
EMS_HOME/lib/jms-2.0.jar (in case of EMS 8.x)
To configure Hawk WebConsole runtime environment, assuming TIBCO Hawk is installed with default supplied Tomcat web server, edit and modify HAWK_HOME/webconsole/startwebconsole.bat and HAWK_HOME/webconsole/tomcat/bin/setenv.bat (the .bat file on Windows, and the .sh file on UNIX/Linux) to set RV_HOME and EMS_HOME correctly.
If you are not using EMS as transport, then it is recommended that you remove the EMS_HOME entries from startwebconsole.bat and setenv.bat (the .bat file on Windows, and the .sh file on UNIX/Linux) files, to avoid any issues with Hawk WebConsole start.
TIBCO Rendezvous Transport
TIBCO Rendezvous can be used as the transport between the Hawk Microagent and Hawk Agent and also between the Hawk Agent and Hawk Console applications.
Configure the -rvd_session parameter in the configuration files to enable the TIBCO Rendezvous as transport.
Comment this option, or let it be commented in the configuration file, if you are using TIBCO EMS or TCP Transport for TIBCO Hawk as the primary transport.
TIBCO Hawk connects to the TIBCO Rendezvous daemon by creating a session. In the configuration files, ensure that the -tcp_session and -ems_transport parameters are commented out, and then configure the -rvd_session parameter. TIBCO Rendezvous transport creation calls accept three parameters that govern the behavior of the transport: service, network and daemon.
-rvd_session <service> <network> <daemon>
where,
service  instructs the Rendezvous daemon to use this service whenever it conveys messages on this transport. You can specify the port number as the service to be used, for example, "7474".
network  instructs the Rendezvous daemon to use a particular network for all communications involving this transport. The network parameter consists of up to three parts, separated by semicolons: network, multicast groups, and send address.
daemon  instructs the transport creation function about how and where to find the Rendezvous daemon and establish communication. For remote daemons, specify two parts (introducing the remote host name as the first part), for example, tcp:7474:
The default value in the configuration file for the Rendezvous session is
-rvd_session 7474 ; tcp:7474
For more details on TIBCO Rendezvous, refer to the TIBCO Rendezvous documentation.
TCP Transport for TIBCO Hawk
TCP Transport for TIBCO Hawk is a TCP based transport for Hawk components using the Akka clustering designs.
For more information about architecture of the TCP Transport for TIBCO Hawk, refer to the TIBCO Hawk Concepts Guide.
To setup the TCP Transport for TIBCO Hawk for Hawk components, you must configure the Hawk components to use the TCP session and join the cluster. The TCP session parameter in the Hawk components requires a unique self socket address and socket address of the Cluster Manager acting as the seed node to join the cluster.
While starting the Hawk components, the Cluster Manager must be started first as the Cluster Manager initiates the cluster for the TCP Transport for TIBCO Hawk.
The following table identifies the files that you must configure to setup the TCP Transport for TIBCO Hawk.
CONFIG_FOLDER\bin\hawktcpdaemon.cfg
Configure the -tcp_session parameter with details to join the TCP transport cluster.
CONFIG_FOLDER\bin\hawkagent.cfg
In case of connection to TIBCO Hawk Microagent (HMA), also uncomment the -ami_rvd_session parameter (in addition to -M AMIService and -ami_tcp_session parameters) for connection using the Hawk TCP-RV Bridge for the TCP Transport for TIBCO Hawk. For TIBCO Hawk Microagent to use the TCP Transport for TIBCO Hawk no configuration is required in hawkhma.cfg.
For more information about -tcp_session, -ami_rvd_session, and -ami_tcp_session parameters for Hawk Agent, see Hawk Agent Configurations.
CONFIG_FOLDER\bin\DomainTransportConfig.yml
- domainName - Specify the Hawk domain name same as specified in the Hawk Cluster Manager (hawktcpdaemon.cfg).
transport - Specify the value as tibtcp for TCP Transport for TIBCO Hawk.
tcpSelfUrl - Specify the socket address of the Hawk Console for joining the cluster.
tcpDaemonUrl - Specify the socket address of the Cluster Manager acting as the seed node for the cluster. This socket address is same as <cluster_manager_IP>:<port> specified for the -tcp_session parameter in the Hawk Cluster Manager (hawktcpdaemon.cfg).
CONFIG_FOLDER\hawkteaagent\config\hawk-domain-transport-cfg.xml
<hk:HawkDomainName> - Specify the Hawk domain name same as specified in the Hawk Cluster Manager (hawktcpdaemon.cfg).
<hk:selfUrl> - Specify the socket address of the Hawk Admin Agent for joining the cluster.
<hk:daemonUrl> - Specify the socket address of the Cluster Manager acting as the seed node for the cluster. This socket address is same as <cluster_manager_IP>:<port> specified for the -tcp_session parameter in the Hawk Cluster Manager (hawktcpdaemon.cfg).
CONFIG_FOLDER\hawk\tibco\cfgmgmt\hawk\bin\hawkevent.cfg
Uncomment the -ami_tcp_session parameter for connecting to the Hawk Agent.
For more information about -tcp_session and -ami_tcp_session parameters for Hawk Event Service, see Hawk Event Service Configurations.
CONFIG_FOLDER\bin\hawkdisplay.cfg
HAWK_HOME\webconsole\tomcat\webapps\hawkwebconsole\WEB-INF\conf\DomainTransportCfg.xml
Uncomment the DomainTransport section with TCP Transport for TIBCO Hawk details and comment the DomainTransport sections for other transports. Specify the following parameters for the TCP Transport for TIBCO Hawk:
<hk:HawkDomainName> - Specify the Hawk domain name same as specified in the Hawk Cluster Manager (hawktcpdaemon.cfg).
<hk:selfUrl> - Specify the socket address of the Hawk WebConsole for joining the cluster.
<hk:daemonUrl> - Specify the socket address of the Cluster Manager acting as the seed node for the cluster. This socket address is same as <cluster_manager_IP>:<port> specified for the -tcp_session parameter in the Hawk Cluster Manager (hawktcpdaemon.cfg).
SSL Configurations for TCP Transport for TIBCO Hawk
To create a secure communication channel between Hawk components, you can configure TCP transport for TIBCO Hawk to use two-way SSL authentication.
You must configure the following SSL parameters for TCP Transport for TIBCO Hawk in each component of TCP Transport Cluster for the secure communication:
For details on these parameters for each component, see the configuration section for each component:
TIBCO Enterprise Message Service (EMS) Transport
This section describes configuration options for connecting to TIBCO EMS server as transport for TIBCO Hawk components.
Comment this option if you are using TCP Transport for TIBCO Hawk or TIBCO Rendezvous as the primary transport.
The two ways to specify the TIBCO EMS transport parameters are:
1.
For example,
-ems_transport tcp://server1:7222
If communicating with the EMS server using SSL, specify the location of the EMS server as follows for the above example
-ems_transport ssl://server1:7222
also specify the additional options as outlined below.
2.
These parameters are separated by a space and can be an empty string to indicate a null value.
For example,
-ems_transport tcp://server1:7222 admin "#!NhAD1NBC"
For instructions to modify the password which was specified during installation, see Handling Passwords for TIBCO EMS Transport.
If communicating with the EMS server using SSL, specify the location of the EMS server as follows for the above example
-ems_transport ssl://server1:7222 admin "#!NhAD1NBC"
and also specify the additional options as outlined in TIBCO Enterprise Message Service (EMS) Transport Using SSL.
Re-Connection Setup
To ensure the TIBCO EMS client attempts re-connection after losing connection to the EMS server, repeat the server URL in the URL list. For example,
-ems_transport tcp://H1:7222,tcp://H1:7222
Fault Tolerance Setup
You can specify backup servers to connect to in the event of the failure of the primary server. The serverURLs for the primary and backup server are specified as a comma-separated list of URLs.
For example,
-ems_transport tcp://server1:7222,tcp://server2:7344
If a connection to the first URL fails, the next URL in the list is used to attempt a reconnection. The connections in the list are attempted in sequence (wrapping to the start of the list, if the first connection was not the failed connection) until all URLs have been tried. If no connection is established after all URLs have been tried, the connection fails.
In addition to specifying the -ems_transport options, the following parameters in the EMS server configuration file, tibemsd.conf, should be considered:
ft_active—the name of the active server.
ft_reconnect_timeout—the amount of time a backup server waits for clients to reconnect.
store—the directory to store TIBCO EMS data.
For more information, see TIBCO Enterprise Message Service documentation.
TIBCO Enterprise Message Service (EMS) Transport Using SSL
Specifies the SSL parameters used by TIBCO Hawk Display when connecting to the EMS server.
If the -ems_transport parameter is not used, the following options are ignored.
-ssl_vendor <name of the vendor>
The name of the vendor of the SSL implementation. The valid choices are
j2se—Use this option when you want to use the default Java Cryptography Extension (JCE) bundled with the Java JRE.
On IBM platforms (such as AIX), this option defaults to ibm.
entrust61—Use this option when you want to use the Entrust libraries.
ibm—On non-IBM platforms, this option can be used only if the IBM version of JCE is installed.
-ssl_ciphers <suite-name>—When specifying this option to specify the cipher suites that can be used, use the ^ qualifier instead of a - qualifier. For more information about specifying cipher suites, refer to the TIBCO Enterprise Message Service documentation.
In addition, the following sets of options are used:
For TIBCO Hawk components to verify the EMS server
-ssl_no_verify_host—If this option is present, it this indicates that the TIBCO Hawk component should not verify the server. Conversely, if this option is not included in the configuration file, it indicates that TIBCO Hawk component should verify the server.
-ssl_trusted—The option specifies the file name of the server certificates. This option can be repeated if more than one certificate file is used.
-ssl_no_verify_hostname—This option specifies that the client should not verify the name in the CN field of the server certificate. Conversely, if this option is not included in the configuration file, it indicates that TIBCO Hawk component should verify the name in the CN field of the server certificate.
-ssl_expected_hostname—The name that is expected in the name of the CN field of the server certificates is specified by this option. The value of this option is used when the -ssl_no_verify_hostname option absent from the configuration file.
If the -ssl_no_verify_host is not specified, the option -ssl_trusted has to be used. Along with the option -ssl_trusted, specify either -ssl_no_verify_hostname or -ssl_expected_hostname.
For the EMS server to verify TIBCO Hawk components
-ssl_identity—This option specifies the digital certificate of the TIBCO Hawk components.
-ssl_private_key—This option indicates the private key of the TIBCO Hawk component. If the key is included in the digital certificate in -ssl_identity, then you may comment this parameter.
-ssl_password—The password to decrypt the identity file of the Hawk component.
Handling Passwords for TIBCO EMS Transport
On Microsoft Windows, the password is obfuscated before it is stored in the Microsoft Windows registry. In order to use the EMS password encrypt/decrypt functionality, all TIBCO Hawk components (including the tibhawkpassword wrapper) have to use JRE 1.8 or above.
If you need to change the user name and password information for the EMS server after installation, a utility is provided to encrypt your password. The following steps detail the use of this utility:
1.
tibhawkpassword -encrypt
2.
3.
For example,
-ems_transport tcp://emsServer:7222 username "#!FrHOG/QbvQMdVk4/wMv/1DA0"
4.
Starting TIBCO Hawk Components
A standalone TIBCO Hawk installation does not need any changes in any of the configuration files for you to execute TIBCO Hawk and its components using TCP Transport for TIBCO Hawk as the default transport. However, if you want to use different or existing transport (TIBCO Rendezvous or TIBCO EMS) or use different port or security, refer to the following table.
These executable or scripts are located in CONFIG_FOLDER/bin and HAWK_HOME/webconsole.
 
 
In any of the above configuration files, if any folder or file has to be configured with a space in it, then the full path has to be provided within double quotes.
On AIX platform, TIBCO HMA process must be started as root user and should not rely on the setuid feature. On other non-Windows platforms, pseudo access may be sufficient, but root privileges are recommended to start TIBCO HMA process.
Hawk Domain
A Hawk domain is a logical grouping of Hawk Components. The Hawk Agent, the Console API and the AMI instrumented applications can all communicate with each other only if they all belong to the same hawk domain. A hawk domain constitutes of a transport and a domain name.
Some components may have additional requirements in order to communicate with the Hawk Agent such as to specify the Hawk Agent name to connect to.
However, the Hawk Console can be configured to manage multiple domains.
If you are using TCP Transport for TIBCO Hawk the Hawk domain must be same for all Hawk components to be part of the cluster.

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved