Installing the TIBCO EMS monitoring extension

Before you begin

• Ensure that the user running the TIBCO EMS monitoring extension (qptibems) has the following rights in the TIBCO EMS server:
  • view-connection
  • view-destination
  • view-durable
  • view-factory
  • view-route
  • view-server

To install the TIBCO EMS monitoring extension on Windows or UNIX 

1. At a command prompt, change to the directory where the TMTM Agents and Extensions are installed.
2. Unzip the contents of the pkg_*_qptibems.zip package, as appropriate for your platform, to a sub-directory of the TMTM Agents and Extensions (e.g. into a directory named qptibems).
3. If you are using the provided Java Runtime Environment (JRE), proceed to Step 4.
   
   If you need to use a different JRE, for example where the provided JRE is no longer current and BMC is not able to provide updates, ensure that JAVA_HOME is set in your environment. See also Defining alternative JREs for Java extensions. Note that on Windows the qptibems.bat and qptibems.conf files will require editing to change the JRE location to be used, unless you want to use the system JAVA_HOME setting.
   

   (UNIX only) After installing 8.1.00 Agent Fix Pack E, QPTIBEMS_JAVA_HOME is used if set, then JAVA_HOME if set. If neither is set, on platforms where a JRE is included in the package that default JRE will be used. 
   
   

4. Reinstalling or upgrading: refer to your backup copies of any configuration (.props) files, or the Windows .bat file and .conf files you may have previously customized. Merge any changes as required.
5. Make sure the TIBEMS_JAVA environment variable is set, and points to the TIBCO EMS Java installation. The default location depends on the TIBCO EMS version. Possible locations are:
   • For Windows: C:\Program Files\tibco\ems\clients\java or C:\Program Files\tibco\ems\ems\8.0\lib
   • For UNIX: /opt/tibco/ems/clients/java
6. (Windows only) Edit the qptibems.conf file and configure the classpath to work with the version of TIBCO EMS being monitored. The default configuration is for TIBCO EMS version 8 (and later). For earlier versions, uncomment the appropriate numbered classpath setting, making sure that the equivalent setting (i.e. one with the same number) is commented out.
   

   # Java Classpath (include wrapper.jar)  Add class path elements as
#  needed starting from 1
wrapper.java.classpath.1=wrapper.jar
wrapper.java.classpath.2=com.bmc.mmpa.eaapi.jar
wrapper.java.classpath.3=qptibems.jar
wrapper.java.classpath.4=log4j-1.2.14.jar
wrapper.java.classpath.5=com.mqs.util.jar
wrapper.java.classpath.6=slf4j-api-1.4.2.jar
wrapper.java.classpath.7=slf4j-log4j12-1.4.2.jar
## uncomment for TIBCO EMS 7 ##
# wrapper.java.classpath.8=%TIBEMS_JAVA%/jms.jar
## uncomment for TIBCO EMS 8 ##
wrapper.java.classpath.8=%TIBEMS_JAVA%/jms-2.0.jar
wrapper.java.classpath.9=%TIBEMS_JAVA%/tibjms.jar
wrapper.java.classpath.10=%TIBEMS_JAVA%/tibjmsadmin.jar
wrapper.java.classpath.11=%TIBEMS_JAVA%/tibcrypt.jar 

7. (UNIX only) Use chmod +x filename to make the following files executable:
   • qptibems.sh
   • Depending on your monitoring needs other files might need to be executable. The binary files for your operating system should be executable.
8. Run qptibems.bat --version or qptibems.sh --version and make sure it works before proceeding. If this errors out, re-visit the steps above.
9. At a command prompt change to the directory where qpea is installed and enter qpea --status to ensure that the TMTM Extensible Agent is running. If it is not running, start it with qpea --start.
10. Change to the directory where you extracted the TIBCO EMS monitoring extension files.
11. If required, set the TMTM Topic Service host name and port:
    • For Windows enter qptibems --config -host:name -port:number
    • For UNIX enter ./qptibems.sh --config -host:name -port:number
      
      where:
      host is the host name or the IP address
      port is the port on the host for the TMTM Topic Service. Omit the port clause to set the port to the default number 15001.
12. (Optional) Set the sample interval by opening file framework.props in a text editor and changing the line:
    
    com.bmc.mmpa.eaapi.framework.waitstate.SampleInterval=60
    This sets the sample interval to 60 seconds, the default.
13. Add a profile for the EMS server:
    • For Windows, enter qptibems --addPref
    • For UNIX, enter ./qptibems.sh --addPref
      
      See Running the TIBCO EMS monitoring extension for all of the available options for the --addPref parameter. At minimum, the command is:
    • For Windows: qptibems --addPref -srv:server -url:tcp://localhost:7222 -usr:username -pwd:password
    • For UNIX: ./qptibems.sh --addPref -srv:server -url:tcp://localhost:7222 -usr:username -pwd:password
14. To register the EMS objects you want to monitor:
    • For Windows, enter qptibems --register -srv:server
    • For UNIX, enter ./qptibems.sh --register -srv:server
      
      This command registers all the objects on the server.
15. (Optional) Set the logging level by opening and modifying the qplog.props file. Your options are info, debug, and warn. Info and warn can be used every day, but debug contains a large amount of data and might not be useful for continual logging. If you elevate the logging level, see the notes in qplog.props about increasing the log file count and/or size to handle the increased amount of data.
16. (For Windows only) Enter qptibems --install to install the TIBCO EMS monitoring extension.
17. Enter qptibems --start (Windows) or qptibems.sh --start (UNIX) to start the TIBCO EMS monitoring extension.
18. (Optional Windows only) Using the Windows Service Manager, configure the TIBCO EMS monitoring extension to start automatically when the computer is restarted. See your operating system's documentation for details.
19. (Optional UNIX only) Using cron or the /etc/rc.d/init.d directory, configure the TIBCO EMS monitoring extension to start automatically when the computer is restarted. See your operating system's documentation for details.

Where to go from here

• To control and configure the extension, see Running the TIBCO EMS monitoring extension.

• To define an alternative JRE, see Defining alternative JREs for Java extensions.
• To view uninstall instructions, see Uninstalling the TIBCO EMS monitoring extension.