Using the agentpref utility to configure agentless monitoring

The agentpref utility enables you to set the parameters that the Agentless Services uses to connect to the remote queue managers.

Run the agentpref command on your Agentless Services computer. The agentpref utility provides a few different ways whereby a remote connection can be defined for the Agentless Services. In each case, you must provide a Queue Manager Name and a Connection string in the IBM WebSphere MQ format of "hostname(port)". You can specify any of the other parameters listed below. If ChannelName is not specified, the channel name "SYSTEM.ADMIN.SVRCONN" is used, which might or might not be valid in your configuration.

The following agentpref options can be used to set the preferences in the eaa.xml file for the Agentless Services:

  • --set-remote-qmgr-csv creates/modifies connection properties for the queue managers listed in the specified CSV file, primarily for use with BMC ADDM integration, see the example below.
  • --import imports an XML file which (among other things) can create/modify connection properties for the queue managers listed in the XML file. See the example below. 

Example of agentpref --import

The agentpref utility can import an XML file that was exported by agentpref. You might also want to create your own—perhaps to create a large number of remote queue manager connection setups with a single command.

To create a large number of remote queue manager connection setups

  1. Create an XML file, similar to the following example. 

    <?xml version="1.0" encoding="UTF-8"?>
    <agentpref Schema="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="agentpref.xsd">
      <WebSphere_MQ_Monitor>
        <QueueManager QmgrName="QMGR1">
          <RemoteConnection ChannelName="SYSTEM.ADMIN.SVRCONN"
           CipherSpecName="OptionalCipherSpecName"
           ConnectionName="qmgrHostName(1414)"
           KeyRepository="OptionalKeyRepositoryPath"
           MQLibrary="CLIENT"
           OCSPResponderURL="OCSP URL"
           RemoteQueueManagerName="RTAP" SecurityExitName="ExitName"
           SecurityUserData="UserData"/>
        </QueueManager>
      </WebSphere_MQ_Monitor>
    </agentpref> 
  2. For each remote queue manager connection that you want to create or modify, repeat the QueueManager. Again, all connection parameters other than QmgrNameChannelName, and ConnectionName are optional.

  3. To import the XML file, run the following command, using the correct parameters for your situation:

    agentpref --host myAgentHostname --port 2612 --import c:\temp\myqmgrs.xml

    Note

    The --notify option is needed only on 7.0 agents and earlier; 8.x agents are notified automatically.

    --notify "WebSphere MQ Monitor" --notify "WebSphere MQ Configuration"

Example of --set-remote-qmgr-csv (BMC Discovery integration)

The agentpref utility can import remote queue manager definitions from a CSV file, although only the Queue Manager Name, Hostname, Port and SVRCONN Channel Name properties can be set in this way.Only the Channel Name property is optional.

Each line in the CSV file represents one remote queue manager definition, with each line containing comma-separated values for QMgrName, Port, Hostname, and SVRCONN ChannelName.  

Example of CSV file

 QMGR1,1414,MyHost,SYSTEM.ADMIN.SVRCONN

If BMC Discovery has been configured to discover the systems where queue managers are running, a query can be executed to extract the details of discovered queue managers and save that information to a file.

To execute a query

  1. Login to the BMC Discovery user interface.
  2. From the Home tab, click the magnifying glass in the upper right of the page, next to the "Search..." field, and select Generic Search.
  3. In the search window, enter the following exactly, if your organization uses a standard SVRCONN Channel name that is not "SYSTEM.ADMIN.SVRCONN", then replace "SYSTEM.ADMIN.SVRCONN" with your organization's standard SVRCONN Channel name in the query:

    search DiscoveredProcess where cmd matches 'runmqlsr' and #Member:List:List:ProcessList.#DiscoveryResult:DiscoveryAccessResult:DiscoveryAccess:DiscoveryAccess._last_marker show extract(args, '(?i)-m\s(\S+)', raw '\1') as 'Queue Manager', extract(args, '(?i)-p\s(\S+)', raw '\1') as Port, #Associate:Inference:InferredElement:SoftwareInstance.#RunningSoftware:HostedSoftware:Host:Host.hostname AS 'Hostname' , 'SYSTEM.ADMIN.SVRCONN' as 'SVRCONN Channel'
  4. Click Export CSV, and save the file on your system (e.g. c:\temp\myqmgrs.xml).
  5. Review the file for correctness. Note that BMC Discovery has no way of knowing the SVRCONN channel name, so it fills in the default, "SYSTEM.ADMIN.SVRCONN". If that is not the correct channel name for any of the queue managers that have been exported, replace it with the correct channel name before going to the next step.
  6. Run the agentpref command to import the file with the command below, filling in the hostname and port number of the target agent as needed.

    agentpref –-host myAgentHostname –-port 2612 –-set-remote-qmgr-csv c:\temp\myqmgrs.csv 

Note

The --notify option is needed only on 7.0 agents and earlier; 8.x agents are notified automatically.

--notify "WebSphere MQ Monitor" --notify "WebSphere MQ Configuration"

Example of agentpref - registering and removing agentless configurations

This version of the command allows you to issue a single command and define one or more remote connection setups. You must specify the Queue Manager Name, Channel Name and Connection Name (e.g., "myhost(1414)"), and you can optionally provide any of the other parameters and their values. You can repeat the entire command and parameters as many times as you like on the command line, in order to create/modify several remote connections.

Register an agentless configuration

The following example shows the syntax to use to register an agentless configuration on Windows (use agentpref.sh for Linux):

agentpref.bat --set "WebSphere MQ Monitor" --pref_path ComMQSoftwareWebSphereMQQueueManager MYQMGR ConnectionName "myhost(1414)" ChannelName MY_CHANNEL MQLibrary "*CLIENT*"

  • where myhost(1414) is the local connection name on which the Extensible Agent (qpea), WebSphere MQ Configuration extension (qpcfg), and WebSphere MQ Monitoring extension (qpmon) are running.
  • where MYQMGR is the queue manager name followed by a defined server connection channel.
  • where MY_CHANNEL is the channel name.

This command creates the queue manager in the Monitor Console under the agent host name. You can then expand the Object Repository tree to see your remote queue manager.

Note

When the target is a TrueSight Middleware and Transaction Monitor version 7 agent or extension, use the following syntax example to register an agentless configuration:

agentpref --host hostname --port 2612 --set-remote-qmgr-info remoteqmgrname SYSTEM.DEF.SVRCONN "remoteqmgrconnectionname"

  • where hostname is the local host name on which the Extensible Agent (qpea), WebSphere MQ Configuration extension (qpcfg), and WebSphere MQ Monitoring extension (qpmon) are running.
  • where remoteqmgrname is the remote queue manager name followed by a defined server connection channel.
  • where remoteqmgrconnectionname is the remote queue manager host name (port).

Remove an agentless configuration

In order to remove an agentless configuration, use the following syntax:

agentpref --remove "WebSphere MQ Monitor" --pref_path ComMQSoftwareWebSphereMQQueueManager QmgrName MQLibrary ChannelName ConnectionName

Note

When the target is a TrueSight Middleware and Transaction Monitor version 7 agent or extension, use the following syntax example to remove an agentless configuration:

agentpref --host hostname --port 2612 --remove-dynamic "WebSphere MQ Monitor" remoteqmgrname-MQLibrary 
agentpref --host hostname --port 2612 --remove-dynamic "WebSphere MQ Monitor" remoteqmgrname-ChannelName 
agentpref --host hostname --port 2612 --remove-dynamic "WebSphere MQ Monitor" remoteqmgrname-ConnectionName

The --notify option is necessary only on 7.0 agents and earlier; 8.x agents are notified automatically.

--notify "WebSphere MQ Monitor" --notify "WebSphere MQ Configuration"

Was this page helpful? Yes No Submitting... Thank you

Comments