BMC Middleware and Transaction Management - How to install Unix Agent and WMQ Extensions? A Runbook

Version 1
    Share This:

    This document contains official content from the BMC Software Knowledge Base. It is automatically updated when the knowledge article is modified.


    PRODUCT:

    BMC Middleware Management - Performance and Availability


    COMPONENT:

    BMC Middleware and Transaction Management


    APPLIES TO:

    BMC Application Transaction Tracing BMC Middleware Management - Performance and Availability BMC Middleware Monitoring BMC TrueSight Middleware Monitor BMC TrueSight Middleware Transaction Monitor



    QUESTION:

    Is there any place where all the steps to install the agent and WMQ extensions is concentrated?


    ANSWER:

     

    Installing BMM 8.0.01 Agents and WMQ Extensions on UNIX

      

    The New Default Layout for Agents and Extensions

      

    The directory layout for agent and extensions is new and different in BMM 8, and is now called the "default layout". BMC recommends that you maintain this layout to ensure compatibility with future releases and features.

      

    The default distribution assumes this layout, and has a default configuration based on this layout (specifically, the location of the Java Runtime Environment).

      

    The default layout is shown below. This layout is created when unzipping the bootstrap package:

      

      <AGENTS>
      +-- agent
      +-- agentpref
      +-- bmmtm-agent
      +-- jre
      +-- qpmon

      

    The root of this directory (<AGENTS> in the example above), is referred to as the directory where the BMTM agents and extensions are installed, and installations typically occur relative to this location.

      

    Configuring the MQS_HOME system environment variable for the Default layout

      

    The BMTM Extensible Agent, BMTM Configuration Agent and most performance and availability monitoring extensions have all the required files located in the directory where they are executed. However, if you wish to consolidate where logging is controlled and where log files reside you may place QPLog.ini in a directory specified by the MQS_HOME system environment variable. This is recommended for supportability.

      

    BTM: The directory specified by the MQS_HOME system environment variable is also used as a well-known location for packages and BTM deployments which are distributed.

      

    BTM: Some TrueSight Middleware and Transaction Monitor extensions and applications which are monitored by a BTM Extension need the MQS_HOME environment variable pointing to a directory with the QPTTAB.DAT and QPLog.ini file. If not set up properly, monitoring of that application can fail due to translation issues and the btm log files may be written to the tmp directory.

      

    To configure the MQS_HOME system environment variable on UNIX

      

    The following approaches can be used for defining the MQS_HOME variable:

      
       
    • /home/$username/.profile or shell equivalent in the users home directory, but this works only for this user when they have a login shell
    •  
    • /etc/profile works globally for all users who have a shell logon
    •  
    • /etc/environment works for all users without a shell login. If you do an su - username the variable is gone, then /etc/profile is used
    •  
    • define it for a service in, for example, xinet.d. In /etc/xinetd.d/service_name add env = MQS_HOME=/directory_path
    •  
    • Control the agent and extensions through shell scripts which have defined MQS_HOME.
      
       
    1. Set and export the system environment variable to a directory of your choice where all logs and other BTM files are to be saved. This should be done from a logon script such as .profile or whatever is applicable for your default shell. This should be the same directory and set for all users which run an extension.
    2.  
    3. Reinitiate your profile to ensure the system environment variable is set. Under Linux it may help to identify if a running process has an environment variable by looking in /proc/PID/env or /proc/PID/environment.
      

    Additional Directories

    The following additional subdirectories may also be used.  

     

      
       
    • MQS_HOME
    •  
    • MQS_HOME/ExtensionConfig
    •  
    • MQS_HOME/AgentDistribution
    •  
    • <AGENTS>/ManualDeployments
    Their purpose:  
       
    • mqs_home is the directory defined in the MQS_HOME system environment variable.
    •  
    • ExtensionConfig is the default directory that contains the extension configuration files. This directory is automatically created and managed by the BMTM Configuration Agent when the system environment variable MQS_HOME is defined (when the BMTM Configuration Agent is started).
    •  
    • AgentDistribution is the default directory that contains the agent distribution files. This directory is automatically created and managed by the BMTM Configuration Agent when the system environment variable MQS_HOME is defined (when the BMTM Configuration Agent is started).
    •  
    • ManualDeployments is a directory for manual deployments of BTM models.
      

     

      

    Distributing the BMTM Extensible Agent and extensions via the launch page

      

    This section describes how to obtain the bootstrap package for your system that contains the BMTM Extensible agent package and other common packages.

      

    To obtain the relevant bootstrap package for your system:

      
       
    1. Open Internet Explorer.
    2.  
    3. Enter http://hostname:15007 in the URL field, where:    
           
      • hostname is the hostname or IP address of the computer running the BMC MTM Application Service
      •    
      • 15007 is the default port used by the BMC MTM Application Service
      •   
    4.  
    5. From the displayed page, click Download Agents. A list of all the supported agent platforms is displayed, with links to download the package in zip, tar, and tgz formats.
    6.  
    7. Choose the Agent Configuration. Default is "Agent does not use a Secure Tunnel Connection". For more information about the other options, see the Installation Guide page 55.
    8.  
    9. Optional: enter a description for the agent. This description can be used with Policies to have certain actions performed when this agent first connects to the services.
    10.  
    11. Download the bootstrap package by clicking the appropriate link to download the package in zip, tar, or tgz format.
    12.  
    13. Transfer the bootstrap package to the target system.
      

    Installing the Bootstrap Package

      

    If you have not made a backup of the agent directory, do so now. The tar utility is recommended over zip.

    Installation steps:  
       
    1. In the command prompt, set your working directory to the directory where the agent installation will reside (<AGENTS>).
    2.  
    3. Verify that the MQS_HOME system environment variable has been configured. Enter
          echo $MQS_HOME
    4.  
    5. Expand the bootstrap package in the <AGENTS> directory.
    6.  
    7. Change to the <AGENTS>/agent directory.
    8.  
    9. Copy QPTTAB.DAT to the directory you defined for the MQS_HOME system environment variable. This file is needed if any of your transactions must have their message format CCSID converted. If you are unsure if any of the message formats must be converted, you should still add this file to the MQS_HOME directory.
    10.  
    11. Make qpea executable, for example:
          chmod +x qpea
    12.  
    13. Start the BMTM Extensible Agent:
          qpea --start
    14.  
    15. Change to the <AGENTS>/bmmtm-agent/bin directory.
    16.  
    17. Start the Configuration Agent, enter:
          agent –-start
      The service connection information was pre-configured in the bootstrap and the Extensible Agent should connect to the BMM server without further configuration.
      Secure Tunnel: Note that the secure tunnel information was also pre-configured in the bootstrap and the Extensible Agent should connect unless additional Secure Tunnel certificate configuration is required.
    18.  
    19. (Optional) Using cron or the /etc/rc.d/init.d directory, configure the BMTM ExtensibleAgent and BMTM Configuration Agent to start automatically when the computer is restarted.
      

     

      

    Note: Although most shells can be used with TrueSight Middleware and Transaction Monitor, many of the script files are written for the Korn shell.

      

    Installing the WebSphere MQ Configuration and Monitoring Extensions on UNIX platforms

      

    Before you begin

      

    Verify that libstdc++.so.6 is installed on Linux. This is required for SSL/TLS because the IBM WebSphere MQ GSKit SSL/TLS libraries supplied with MQ depend on libstdc++.so.6.

      

    Ensure that the BMTM Extensible Agent is installed on the agent machine.

       NOTE: The WebSphere MQ Monitoring and Configuration extensions must be able to find the local MQ installation (either the server for Agent based configurations or the MQ Client for agentless configurations) on the installed host. The extensions look in the default installation location automatically, but may fail to locate the installation when multiple WebSphere MQ versions are installed (in MQ 7.1 and above), when WebSphere MQ is not installed in the default location, or when no WebSphere MQ 7.x is designated as the primary installation. In these situations you must configure the WebSphere MQ Monitor preference DefaultMQInstallationPath to point to the path to any valid WebSphere MQ installation. This can be configured via the Configuration Manager Agent Preferences dialog or via   agentpref.  

     

      

    IBM WebSphere MQ 7.0.1 single version installation

      
       
    • On AIX with 32/64-bit Queue Managers and IBM WebSphere MQ symbolic links are pointing from /usr/lib/ to /usr/mqm/lib, you need to set the LIBPATH environment variable to contain the 64 IBM WebSphere MQ library directories. They should precede other directories, as in the examples below.
    •  
    • On AIX with 64-bit Queue Managers without IBM WebSphere MQ symbolic links pointing from /usr/lib/ to /usr/mqm/lib, set the DefaultMQInstallationPath with agentpref.
    •  
    • On all other UNIX/Linux IBM WebSphere MQ 7.0.1 installations, set the DefaultMQInstallationPath with agentpref.
      

    IBM WebSphere MQ 7.1, MQ 7.5 and 8.x single installation with default installation path

      

    No specific action is required.

      

    IBM WebSphere MQ 7.x and 8.x single installation with non-default installation path

      

    Set DefaultMQInstallationPath with agentpref.

      

    IBM WebSphere multi-version installations

      

    Set DefaultMQInstallationPath with agentpref to the most recent IBM WebSphere MQ version.

      

    Agentpref examples:

    The   agentpref utility is installed in the   <AGENTS>/agentpref directory.  
       
    • AIX: agentpref.sh --set "WebSphere MQ Monitor" DefaultMQInstallationPath /usr/mqm
    •  
    • Linux: agentpref.sh --set "WebSphere MQ Monitor" DefaultMQInstallationPath /opt/mqm
      

    You may encounter a port conflict for port 6001 betwen the WebSphere MQ Monitoring Extension (and qpmon) and The X WIndow System on UNIX. The qpmon port is changeable and can be redefined as necessary. The port is changed by setting the ServicePort extension preference:
         agentpref.sh --set "WebSphere MQ Monitor" ServicePort 6001

      

    Restart the agent and extensions after making this change.

      

    To install the WebSphere MQ Configuration and Monitoring Extensions on a UNIX platform

      
       
    1. Open a command prompt and change to the <AGENTS>/qpmon directory.
    2.  
    3. Make the following files executable; for example:
          chmod +x qpmon
          chmod +x qpcfg
    4.  
    5. At a command prompt change to <AGENTS>/agent.
    6.  
    7. If you are reinstalling or upgrading the BMTM Extensible Agent:    
           
      1. Enter:
            qpea --status
        This is to check that the BMTM Extensible Agent is running. If it is running, stop it with:
            qpea --stop
      2.    
      3. Restore your backup copy of the eaa.xml file to the <AGENTS>/agent directory.
      4.   
    8.  
    9. Install and start the extensions:    
           
      • Enter:
            qpea --status
        This is to check that the BMTM Extensible Agent is running. If it is not running, start it with:
            qpea --start
      •    
      • Start the configuration extension. Enter:
            qpcfg.sh --start
      •    
      • Starr the monitoring extension. Enter:
            qpmon.sh --start
      •   
    10.  
    11. (Optional) Using cron or the /etc/rc.d/init.d directory, configure the BMTM Extensible Agent and WebSphere MQ extensions to start automatically when the computer is restarted.
      

    WARNING regarding 32-bit extensions and WebSphere MQ 64-bit commands: When running some BMTM Extensible Agent extensions (qpmon, qpcfg) you may run into a problem where the extensions attempt to load the wrong WebSphere MQ libraries. Whether this occurs depends on the version of the executables (32-bit or 64-bit), the version (and location) of the WebSphere MQ installation, and the entries in the library path.
    This is an example of the error:

      

    exec(): 0509-036 Cannot load program qpcfg because of the following errors: 0509-150 Dependent module /usr/mqm/lib64/libmqm.a(libmqm.o) could not be loaded.
    0509-103 The module has an invalid magic number.

      

    Beginning with WebSphere MQ 6, WebSphere MQ uses 64-bit commands and supplies lib and lib64 directories containing shared libraries that the extensions use (e.g. libmqm).

      

    Most of TrueSight Middleware and Transaction Monitor’s extensions are 32-bit and require the 32-bit versions of the WebSphere MQ libraries. These extensions could fail to start if the library path (LIBPATH / LD_LIBRARY_PATH) includes WebSphere MQ’s lib64 directory before its lib directory. (The inverse could also occur for the 64-bit extensions if the lib directory is specified before the lib64 directory.) To prevent the error, ensure that the library path is set correctly (the lib directory appear before the lib64 directory).

      

    You must keep both directories on the path because WebSphere MQ programs still require a reference to the lib64 directories to run.

      

    Additionally, IBM hard-coded a path into their commands using RUNPATH. RUNPATH can help ensure that the correct libraries are loaded, but only if WebSphere MQ is installed in the default location. If the default location is not used, then setting the proper library path may be required.

     


    Article Number:

    000105281


    Article Type:

    FAQ/Procedural



      Looking for additional information?    Search BMC Support  or  Browse Knowledge Articles