Introduction

This article shows you how to make IBM® WebSphere® MQ FTE agents highly available using Microsoft® Cluster Service (MSCS), which provides high availability of data and applications by grouping physical servers together in a cluster. An MSCS cluster consists of two or more servers, with disk storage shared between the servers, and a virtual or floating IP address that presents a single IP address to client applications connecting to the cluster. Each cluster also has another shared disk, known as a quorum disk, which is used exclusively by MSCS.

In this article the term cluster refers to an MSCS cluster, not a WebSphere MQ Cluster. To benefit from this article, you should have a basic understanding of MSCS in relation to WebSphere MQ. The article does not cover the details of configuring WebSphere MQ for these scenarios.

In hardware terms, a typical two-server MSCS cluster looks like this:

Configuring MSCS and WebSphere MQ

For all scenarios in this article, MSCS is configured in Active/Passive mode. All work is directed to one server and the other server is up and running but does not have WebSphere MQ queue managers running on it. If the first server encounters any of a number of pre-defined failure conditions, the applications, in this case WebSphere MQ, and in Scenario 2, the WebSphere MQ FTE agent, are restarted on the other server.

Configuring MSCS

Here is the MSCS configuration used for this article:

• A service named mscs-mq01, which in turn has the following resources:
• Two nodes, nodeA and nodeB
• A SAN disk shared between the two nodes named Cluster_Disk 1 -- this disk is mounted as drive D on the currently active node
• A Quorum disk named Quorum_Cluster_Disk mounted as Drive Q – this disk is mounted on the currently active node
• A floating IP address (10.101.16.71) that points to the currently active node

Configuring WebSphere MQ with MSCS

Before starting, WebSphere MQ must be installed and a WebSphere MQ queue manager (QMA) must be created and put under MSCS control. The scenarios will use a single queue manager acting as the coordination, command, and agent queue manager. For information on configuring WebSphere MQ for use with MSCS, see Supporting MSCS in the WebSphere MQ information centre. The installation of WebSphere MQ is identical on both nodeA and nodeB, and the user IDs used by WebSphere MQ are set up as described in the information centre link above.

WebSphere MQ FTE and MSCS scenarios

This article describes the configuration of WebSphere MQ FTE with MSCS in the following five scenarios:

• Scenario 1: Agent started through a WebSphere MQ service outside MSCS control
• Scenario 2: Agent started as a generic application within the MSCS queue manager group
• Scenario 3: Agent remote to MSCS cluster, accessing MSCS agent queue manager over TCP/IP
• Scenario 4: Agent remote to MSCS, locally bound to its agent queue manager, accessing MSCS clustered queue manager
• Scenario 5: Agent created as a Windows® service and started as a generic service within the MSCS queue manager group (WebSphere MQ FTE V7.0.3 only)

For Scenarios 1 to 4, the configuration described in this article was built using Windows Server Enterprise 2008, WebSphere MQ V7.0.1, and WebSphere MQ FTE V7.0.2.1. The configuration for Scenario 5 was built using Windows Server Enterprise 2008, WebSphere MQ V7.0.1, and WebSphere MQ FTE V7.0.3.

Scenario 1: Agent started through a WebSphere MQ service outside MSCS control

For Scenario 1, an instance of an agent, for example AG_TEST1_QMA, is configured on both nodeA and nodeB using QMA as their agent queue manager. The configuration directory for both instances resides on the local disk of each machine. When the queue manager QMA is started on either node by MSCS, it starts the local instance of the WebSphere MQ FTE agent by the use of a WebSphere MQ service definition.

With this configuration, file transfers must not use the file systems local to nodeA and nodeB, and must use storage on the shared file system managed by MSCS. If the local file systems are used, the file transfers could get into an inconsistent state. With this scenario, the WebSphere MQ FTE agent is outside of MSCS control, so if the WebSphere MQ FTE agent fails, MSCS will not attempt to restart or fail over to the other node. The configuration of Scenario 1 is described in the following steps:

1. Install and configure WebSphere MQ FTE server on both nodes in the cluster
2. Create the WebSphere MQ FTE agent on the first node
3. Create the WebSphere MQ FTE agent on the second node
4. Define a WebSphere MQ service to start the agent on queue manager start
5. Simulating failover

Install and configure WebSphere MQ FTE server on both nodes in the cluster

Make sure queue manager QMA is running on nodeA. Using either the GUI or the console installer, install WebSphere MQ FTE onto both nodes in the cluster. The WebSphere MQ FTE installation must be identical on both nodes that are installed into the same location using the same user IDs created on both nodes. When prompted for the configuration location, specify a location on the local drive, not a cluster drive. All further examples in this scenario assume this default WebSphere MQ FTE data location:

 
C:\Documents and Settings\All Users\Application Data\IBM\WMQFTE\config

In the GUI installer, select the check box to skip configuration on the "Enter coordination queue manager name" step. If you are using the console installer, enter Yes to skip the configuration. After the product is installed, use the fteSetupCoordination command to set the WebSphere MQ FTE coordination queue manager to QMA:

 
fteSetupCoordination -coordinationQMgr QMA

Use the QMA.mqsc file generated by the fteSetupCoordination command as input to the WebSphere MQ runmqsc command to define the WebSphere MQ objects required for WebSphere MQ FTE coordination:

 
runmqsc QMA < "C:\Documents and Settings\All Users\Application Data\IBM\
    WMQFTE\config\QMA\QMA.mqsc"

Then set the command queue manager by using the fteSetupCommands command. No mqsc commands are generated by fteSetupCommands so there is no need to run runmqsc for this step:

 
fteSetupCommands -connectionQMgr QMA

Create the WebSphere MQ FTE agent on the first node

Before creating the WebSphere MQ FTE agent on the first node, make sure that the WebSphere MQ queue manager QMA is active on the first node. If it is not active, use the MSCS Failover Cluster Management console to move the MSCS service mscs-mq01 to nodeA. Use the fteCreateAgent command to create the agent on the first node, specifying QMA as the agent queue manager:

 
fteCreateAgent -agentName AG_TEST1_QMA -agentQMgr QMA

Use the AG_TEST1_QMA_create.mqsc file generated by the fteCreateAgent command as input to the WebSphere MQ runmqsc command to define the WebSphere MQ objects required for the WebSphere MQ FTE agent:

 
runmqsc QMA < "C:\Documents and Settings\All Users\Application Data\IBM\
    WMQFTE\config\QMA\agents\AG_TEST1_QMA\AG_TEST1_QMA_create.mqsc"

Start the agent to confirm that it starts cleanly and then use fteStopAgent to stop it. Make sure the agent has stopped before continuing to the second node.

Create the WebSphere MQ FTE agent on the second node

After the agent is created on the first node, create the partner instance of the agent on the second node. Use MSCS Failover Cluster Management to move the MSCS service queue manager over to nodeB by moving the MSCS service mscs-mq01 to nodeB. When QMA has restarted on nodeB, create the WebSphere MQ FTE agent on nodeB using the same command you used on nodeA:

 
fteCreateAgent -agentName AG_TEST1_QMA -agentQMgr QMA

This time, the WebSphere MQ objects for AG_TEST1_QMA do not need to be created using runmqsc, because it was already done when creating the same agent on nodeA. Again make sure the agent starts cleanly on nodeB using fteStartAgent and then shut it down using fteStopAgent.

Define a WebSphere MQ service to start the agent on queue manager start

In this scenario, the WebSphere MQ FTE agent is not under the control of MSCS, so when queue manager QMA fails over to the other node in the cluster, the agent must be started via other means. You can use WebSphere MQ service definition for this purpose, and you can define it using WebSphere MQ Explorer or the following MQSC command:

 
DEFINE SERVICE ('AGT1_SERVICE') +
       DESCR('Start WMQFTE Agent when queue manager starts') +
       STARTCMD('"C:\WMQFTE\bin\fteStartAgent.cmd" AG_TEST1_QMA') +
       STARTARG(' ') + 
       STOPCMD(' ') +
       STOPARG(' ') +
       STDOUT('C:\Documents and Settings\All Users\Application Data\-
IBM\WMQFTE\config\QMA\agents\AG_TEST1_QMA\logs\stdout_WMQService-
.log') +
       STDERR('C:\Documents and Settings\All Users\Application Data\-
IBM\WMQFTE\config\QMA\agents\AG_TEST1_QMA\logs\stderr_WMQService-
.log') +
       CONTROL(STARTONLY) +
       SERVTYPE(COMMAND) +
       REPLACE

This service definition uses a SERVTYPE of COMMAND. If SERVTYPE on SERVICE is used, then the status of the WebSphere MQ FTE agent isn't shown correctly in the service in WebSphere MQ Explorer, because SERVTYPE(SERVICE) assumes the service it is starting is a long running process that it can check the status of. When fteStartAgent is called. it creates a separate JVM for the agent to run in and then exits. As the fteStartAgent command is then not long running, if SERVTYPE(SERVICE) was used when the fteStartAgent command completed, the service would show as stopped when the agent itself is still running. A potential workaround is to run the agent in the foreground under the same process as the fteStartAgent command. The STDOUT and STDERR parameters on the WebSphere MQ service definition have the filenames stdout_WMQService.log and stderr_WMQService.log, because WebSphere MQ FTE agents use stdout.log and stderr.log in the same directory, so the WebSphere MQ Service logs are named differently to avoid a clash.

As the queue manager is already running on nodeB, start AG_TEST1_QMA: right-click on the AGT1_SERVICE service and select Start. WebSphere MQ Explorer will report that the start was accepted with message AMQ4151. Use the ftePingAgentCommand to confirm the agent is running:

 
ftePingAgent AG_TEST1_QMA 

If the agent is running, then the ftePingAgent response will look like this:

 
> ftePingAgent AG_TEST1_QMA 
5655-U80, 5724-R10 Copyright IBM Corp.  2008, 2009.  ALL RIGHTS RESERVED
BFGCL0212I: Issuing ping request to agent AG_TEST1_QMA
BFGCL0213I: agent AG_TEST1_QMA responded to ping in 0.422 seconds.

If there is a problem, then the ping request will time out. Five seconds is the default timeout period, and you can change it using the –w parameter on the ftePingAgent command:

 
> ftePingAgent -w 5 AG_TEST1_QMA 
5655-U80, 5724-R10 Copyright IBM Corp.  2008, 2009.  ALL RIGHTS RESERVED
BFGCL0212I: Issuing ping request to agent AG_TEST1_QMA
BFGCL0214I: agent AG_TEST1_QMA didn't respond to ping after 5 seconds.

The service definition also uses CONTROL(STARTONLY), because if CONTROL is set to QUEUE MANAGER, so that the fteStopAgent command is issued when a request to stop the queue manager is received, then the queue manager may start to quiesce and stop before the WebSphere MQ FTE agent has processed the stop request. Depending on the MQ configuration, the stop agent command may then hit the agent queue manager queues after the agent has been restarted on the partner node, and the agent would be seen to start then subsequently stop for no apparent reason. So the approach used in this article is to make the WebSphere MQ Service issue the fteStartAgent command whenever the queue manager starts. If an instance of the WebSphere MQ FTE agent is already running, then the fteStartAgent command will fail with the following message recorded in the stderr_WMQService.log:

 
BFGCL0029E: Another instance of agent 'AG_TEST1_QMA' is already running.

Stop the agent by right-clicking on the AG_TEST1_QMA service in WebSphere MQ Explorer and selecting Stop. You will be prompted to confirm the Stop request by message AMQ4132 -- click Yes. Confirmation of the Stop request is confirmed by message AMQ4152. Then use ftePingAgent or check the agent logs to confirm that the agent has stopped. Finally for this step, restart the agent via the WebSphere MQ service on nodeB so that everything is running on nodeB.

Simulating failover

When failing over the clustered queue manager, certain agent behaviour will be reported in the agent log files that might in a non-MSCS environment be deemed unusual. In a catastrophic failover situation, nodeA might just crash, in which case none of the messages described below will be seen. The following description is for a "clean failover."

To simulate a failover, you can use the simulate failover option in the MSCS Failover Management Console to simulate the situation where nodeB has failed, and everything is to be restarted on nodeA. After a short while, MSCS will report that the service mscs-mq01 and all its constituent parts (QMA, Cluster_Disk_1, Quorum_Disk, and the IP address) have moved back to nodeA and are running. When QMA restarted on nodeA, the WebSphere MQ Service AG_TEST1_QMA will have started the agent AG_TEST1_QMA on nodeA. Use the ftePingAgent command as above to confirm that this is the case. On this occasion you will not see any WebSphere MQ FTE agent activity on nodeB, as the last thing the agent did on nodeB was to shut down. Next, simulate failover again so that everything moves back to nodeB. When failover to nodeB has completed, confirm that AG_TEST1_QMA is running on nodeB with ftePingAgent. In the agent logs for AG_TEST1_QMA on nodeA, you will see the following message:

 
BFGAG0046W: A binding's transport mode connection cannot be established 
to queue manager 'QMA'.  The reason code is 2162.  The agent 
will retry the operation every 30 seconds.

Remember that the WebSphere MQ service defined to start AG_TEST1_QMA was defined with the option CONTROL(STARTONLY), so when QMA is shut down, there is no attempt to shut down the WebSphere MQ FTE agent AG_TEST1_QMA. If MSCS moves QMA to nodeB within the 30 second retry period, then the agent is no longer able to establish whether the queue manager actually exists (as now the queue manager has moved to nodeB), and so this is treated as an unrecoverable error and the agent ends. The following two messages will be in AG_TEST1_QMA’s log file on nodeA:

 
BFGAG0050E: The agent received MQI reason code 2058 when establishing a 
binding's transport mode connection to the queue manager 'QMA'.  The agent
cannot continue and will end. 
BFGAG0061E: The agent ended abnormally

If the queue manager wasn't moved to nodeB within the 30 second retry period, the queue manager still exists on nodeA and the Agent treats this as a recoverable error, as it would in any situation where the queue manager is stopped. The Agent will output the following message to its log file on nodeA:

 
BFGAG0046W: A binding's transport mode connection cannot be established to 
queue manager 'QMA'.  The reason code is 2059.  The agent will 
retry the operation every 30 seconds.

When MSCS starts queue manager QMA on nodeB, the WebSphere MQ service will issue the fteStartAgent command for AG_TEST1_QMA and the agent log files on nodeB should report a successful agent start.

Scenario 2: Agent started as a Generic Application within the MSCS queue manager group

In Scenario 2, the agent AG_TEST1_QMA is part of the MSCS cluster as an MSCS generic application, which is an application that is not cluster aware and does not use any of the cluster APIs or cluster control code to communicate with the cluster. For a generic application, the only check that MSCS can do is to confirm that the generic application's process is still running. In this scenario, it is fteStartAgent that is registered as a generic application, and it spawns the agent process that is long running, and then fteStartAgent terminates. Therefore MSCS will not be able to detect a failure of the WebSphere MQ FTE agent. But if there is a failure in the other MSCS managed components, then agent will be restarted by MSCS on the other node. Configuration of Scenario 2 is described in the following steps, which assume that steps 1.1 and 1.2 (Configuring MSCS, and Configuring WebSphere MQ with MSCS) above have been completed.

• Install and configure WebSphere MQ FTE server on both nodes in the cluster
• Create the WebSphere MQ FTE agent on the first node
• Put the agent under MSCS control
• Simulating failover

Install and configure WebSphere MQ FTE server on both nodes in the cluster

For this scenario, WebSphere MQ FTE is installed locally on each of the nodes, but unlike in Scenario 1, the Agent's configuration directory will be on a cluster disk tied to the same MSCS group as the agent queue manager (Cluster_Disk1), which can then be moved between the nodes on failover.

Install WebSphere MQ FTE on both nodes in the cluster as described in Scenario 1. However, the configuration directory must be on a shared disk that is managed by MSCS, rather than on a file system local to that node. Additionally the commands fteSetupCoordination and fteSetupCommands do not need to be run on the second node, because in this scenario, the configuration is shared across the nodes.

Create the WebSphere MQ FTE agent on the first node

Use the procedure outlined in Scenario 1 above to create the agent AG_TEST1_QMA on the first node (nodeA). Start the agent and use the ftePingAgent command to confirm that it has started successfully. Finally, use fteStopAgent to stop the agent.

The agent AG_TEST1_QMA does not need to be created on the second node in this scenario because the agent's configuration information is stored on Cluster_Disk1 and the queue manager QMA, with QMA holding the WebSphere MQ objects required by AG_TEST1_QMA that are made available to the currently active node by MSCS.

Put the agent under MSCS control

Next, register the fteStartAgent command as a generic application with MSCS. As described above, registering fteStartAgent as a generic application ensures that MSCS attempts to start the agent when the application mscs-mq01 is failed over.

 
cluster.exe /cluster:MyCluster res "fteStartAgent Application" 
            /create /group:"mscs-mq01" /type:"Generic Application" /priv 
            CommandLine="C:\progra~1\ibm\wmqfte\bin\fteStartAgent.cmd -F 
            AG_TEST1_QMA" /AddDep:"Cluster IP Address" /AddDep:"Cluster Disk 1" 
            /priv CurrentDirectory="D:\"

As stated above in this scenario, agent AG_TEST1_QMA will not be stopped by MSCS in a controlled manner when MSCS fails over. When a failover occurs, the Agent will go through a cycle of retry then shutdown, as described in Scenario 1: Simulating failover. But in contrast to Scenario 1, as the agent's log files have been failed over to the other node, the agent is unable to log any information and silently shut down.

Start the agent from the MSCS Failover Management Console by using the Start option on the MSCS generic application configured for fteStartAgent AG_TEST1_QMA. After the agent has started, use ftePingAgent to confirm that it is running.

Simulating failover

To simulate failover, use the Simulate Failover function provided by the MSCS Failover Management Console. After a short while, MSCS will report that the service mscs-mq01 and all its constituent parts (QMA, Cluster_Disk1 holding Agent Configuration, Quorum_Disk, and the IP address) have moved to nodeB and are running. After QMA restarts on nodeB, MSCS will start the agent AG_TEST1_QMA on nodeB. Use the ftePingAgent command as above to confirm that this is the case.

Looking back on nodeA, the agent will shut down as described above in Scenario 1. But unlike in Scenario 1, as the agent no longer has access to its log files, it has no mechanism to report this. One way to confirm that the agent is no longer running is to note the process id of the agent before failover in the agent.lck file in the agent's configuration directory. After failover, you should eventually no longer be able to see that process using the Windows Task Manager or Process Explorer.

Scenario 3: Agent remote to MSCS cluster accessing MSCS agent queue manager over TCP/IP

In Scenarios 1 and 2, the agent AG_TEST1_QMA was configured to run on the same machines as the WebSphere MQ queue manager QMA. In Scenario 3, the Agent (AG_TEST1_QMA) will be configured to run on a separate machine outside of the cluster to QMA via a WebSphere MQ server connection channel to queue manager (QMA). Therefore that agent does not get restarted when its queue manager is fails over. When an MSCS failover occurs, the connection between the Agent and queue manager is temporarily broken. The agent goes into a retry state until the queue manager has been restarted on the other MSCS node. At this point, the connection between the agent and queue manager is re-established. The following steps describe the configuration of Scenario 3. These steps assume that Steps 1.1 and 1.2 (Configuring MSCS and Configuring WebSphere MQ with MSCS) above have been completed.

• Install WebSphere MQ FTE client on the remote machine
• Create the WebSphere MQ FTE agent on the remote machine
• Configure MSCS queue manager for WebSphere MQ FTE
• Start the remote agent
• Simulating failover on the MSCS cluster

Install WebSphere MQ FTE client on the remote machine

Install the WebSphere MQ FTE client code on the remote machine where the WebSphere MQ FTE agent is going to run. Since the machine is not part of the MSCS Cluster, it can be any WebSphere MQ FTE supported platform, and WebSphere MQ does not need to be installed on this remote machine. Using the GUI installer, accept the license agreement, and accept the default locations for the installation and configuration folder. Opt to skip the configuration as described in the previous scenario installations. After the installation has completed, use the fteSetupCoordination command to specify the coordination queue manager. For example:

 
fteSetupCoordination -coordinationQMgr QMA -coordinationQMgrHost 10.101.16.71 
                     -coordinationQMgrPort 1414 
                     -coordinationQMgrChannel SYSTEM.DEF.SVRCONN

Unlike the previous scenarios, notice that this time, the coordinationQMgrHost, coordinationQMgrPort, and coordinationQMgrChannel parameters need to be specified to tell the WebSphere MQ FTE client to connect to the coordination queue manager. The coordinationQMgrHost parameter must use the MSCS-managed virtual IP address (or hostname) that switches between the MSCS nodes on failover. Do not use the local IP addresses of either of the nodes. The generated mqsc script must be run on the coordination queue manager to generate the WebSphere MQ objects that WebSphere MQ FTE requires, as described in Configure MSCS queue manager for WebSphere MQ FTE.

Next, you must run fteSetUpCommands to determine the WebSphere MQ FTE command queue manager. Again, a server connection channel must be used to connect into QMA specifying the MSCS-managed virtual IP address. As a single queue manager is being used as the coordination, command, and agent queue manager, the values for the host, port, and channel will be the same as the fteCreateCoordination command. For example:

 
fteSetupCommands -connectionQMgr QMA -connectionQMgrHost 10.101.16.71
                 -connectionQMgrPort 1414 
                 -connectionQMgrChannel SYSTEM.DEF.SVRCONN

Create the WebSphere MQ FTE agent on the remote machine

The next step is to create the WebSphere MQ FTE agent AG_TEST1_QMA on the remote machine. As in Scenarios 1 and 2, the fteCreateAgent command is used, but for Scenario 3, the agent queue manager, QMA, is running on one of the MSCS-managed nodes so you need to use a WebSphere MQ server connection channel to connect into QMA. As with the previous commands, the MSCS-managed virtual IP address must be used to connect into the MSCS cluster. Here is an example of an fteCreateAgent command to do this:

 
fteCreateAgent -agentName AG_TEST1_QMA -agentQMgr QMA 
               -agentQMgrHost 10.101.16.71 -agentQMgrPort 1414 
              -agentQMgrChannel SYSTEM.DEF.SVRCONN

As with the fteCreateCoordination command, once the fteCreateAgent command has run successfully, you must run the mqsc file (AG_TEST1_QMA_create.mqsc) against the cluster queue manager (QMA). This process defines the agent-specific WebSphere MQ objects, as described in the next section.

Configure MSCS queue manager for WebSphere MQ FTE

This scenario does not require a specific installation of WebSphere MQ FTE on the cluster machines, as they are used purely as hosts for the WebSphere MQ FTE queue manager.

From the steps in Install WebSphere MQ FTE client on the remote machine and Create the WebSphere MQ FTE Agent on the remote machine, two mqsc scripts are generated on the remote machine -- QMA.mqsc and AG_TEST1_QMA_create.mqsc. Copy both scripts to the cluster node currently hosting QMA, and run the scripts against the queue manager (the queue manager must be running):

 
runmqsc QMA < QMA.mqsc 
runmqsc QMA < AG_TEST1_QMA_create.mqsc

The first script generates the WebSphere MQ objects that enable QMA perform the role of coordination queue manager. The second script generates the WebSphere MQ objects required by the remote agent.

Start the remote agent

The agent AG_TEST1_QMA on the remote machine can now be started by using the fteStartAgent command:

 
fteStartAgent –F AG_TEST1_QMA

The –F switch forces the agent to run in the foreground in a command window, so that you can see what the agent is doing when the queue manager fails over on the MSCS cluster without having to view the Agent log files. When the agent starts successfully, the following messages appear in the command window:

 
BFGAG0058I: The agent has successfully initialized. 
BFGAG0059I: The agent has been successfully started.

Now use ftePingAgent to confirm that AG_TEST1_QMA is able to communicate with its agent queue manager. Leave the AG_TEST1_QM running and continue to the next step.

Simulating failover on the MSCS cluster

To simulate failover use the Simulate Failover function provided by the MSCS Failover Management Console. When MSCS initiates a failover, QMA is stopped on the currently active node. At this point the following message appears in the command window for AG_TEST1_QMA on the remote machine:

 
BFGAG0048W: A client transport mode connection cannot be established to queue 
manager 'QMA' on host '10.101.16.71', port '1414' and using channel 
'SYSTEM.DEF.SVRCONN'.  The reason code is 2059.  The agent will retry the 
operation every 30 seconds.

As far as AG_TEST1_QMA is concerned, QMA has just stopped. If MSCS doesn't start QMA on the other node within 30 seconds, which is unlikely, then another instance of this message appears. When QMA is restarted on the other MSCS node, the following message appears in the AG_TEST1_QMA command window:

 
BFGAG0057I: The agent has established a client transport mode connection to 
queue manager 'QMA' on host '10.101.16.71', port '1414' and channel 
'SYSTEM.DEF.SVRCONN'.  The agent is ready to be used for transfers.

The ftePingAgent command for AG_TEST1_QMA will confirm that AG_TEST1_QMA is now ready for transfers.

Scenario 4: Agent remote to MSCS, locally bound to its agent queue manager, accessing MSCS clustered queue manager

Scenario 4 is similar to Scenario 3, except that this time the remote agent (AG_TEST1_QMB) connects a queue manager local (QMB) to the agent machine. The agent connects in bindings mode to QMB, which in turn connects to the clustered queue manager (QMA) via a WebSphere MQ sender/receiver channel pair. Only queue manager QMA is under the control of MSCS. Agent AG_TEST1_QMB and queue manager QMB are not controlled by MSCS. By definition, as this scenario requires a local queue manager on the remote machine, WebSphere MQ must be installed and configured on the machine. The configuration of Scenario 4 is described in the following steps. These steps assume that Steps 1.1 and 1.2 (Configuring MSCS and Configuring WebSphere MQ with MSCS) above have been completed:

• Create queue manager QMB on the remote machine
• Install WebSphere MQ FTE Server on the remote machine
• Create the WebSphere MQ FTE agent on the remote machine
• Configure MSCS queue manager for WebSphere MQ FTE
• Start the remote agent
• Simulate a failover on the MSCS cluster

Create queue manager QMB on the remote machine

Create the queue manager QMB on the remote machine and connect it to QMA using a WebSphere MQ sender/receiver channel pair. Remember to use the virtual IP address managed by MSCS in the connection name for the WebSphere MQ channel definitions. Make sure that the WebSphere MQ channels between QMB and QMA are running, or configure them to use triggering to start when a message arrives on the respective transmission queues.

Install WebSphere MQ FTE server on the remote machine

Install the WebSphere MQ FTE server code on the remote machine where the WebSphere MQ FTE agent is going to run. The server edition of WebSphere MQ FTE must be used so that the agent can connect to a local queue manager in bindings mode. If the FTE client edition is installed, agents configured under that installation will only be able to connect to a queue manager using WebSphere MQ client connection channels. If the FTE Client installation used for Scenario 3 is used, when attempting to start the agent, the agent will end with the following message:

 
BFGAG0077E: The licence terms of the WebSphere MQ File Transfer Edition Client 
   do not permit bindings transport mode connections to be used to 
   connect an agent process to the queue manager.
BFGAG0061E: The agent ended abnormally

You can however use a WebSphere MQ FTE client installation in this kind of scenario, by connecting to the local queue manager over TCP/IP via a valid port and server connection channel for the queue manager for the agent and command queue manager configuration. However the configuration of the agent and commands in this situation is not covered in this article.

Using the GUI installer, accept the license agreement and default locations for the installation and configuration folder. Opt to skip the configuration as described in the previous scenario installations. After the installation has completed, use the fteSetupCoordination command to specify the coordination queue manager. For example:

 
fteSetupCoordination -coordinationQMgr QMA -coordinationQMgrHost 10.101.16.71 
         -coordinationQMgrPort 1414 
         -coordinationQMgrChannel SYSTEM.DEF.SVRCONN

As with Scenario 3 above, notice that this time, the coordinationQMgrHost, coordinationQMgrPort and coordinationQMgrChannel parameters need to be specified to tell the WebSphere MQ FTE client to connect to the coordination queue manager. The coordinationQMgrHost parameter must use the MSCS-managed virtual IP address (or hostname) that switches between the MSCS nodes on failover. Do not use the local IP addresses of either of the nodes. The mqsc script that is generated must be run on the coordination queue manager to generate the WebSphere MQ objects that WebSphere MQ FTE requires, as discussed in "Configure MSCS Queue Manager for WebSphere MQ FTE."

Next, run the fteSetupCommands command to specify the WebSphere MQ FTE command queue manager. Unlike previous scenarios, use the local queue manager (QMB) as the command queue manager.

 
fteSetupCommands -connectionQMgr QMB

Create the WebSphere MQ FTE agent on the remote machine

The next step is to create the WebSphere MQ FTE agent AG_TEST1_QMB on the remote machine. As in Scenarios 1 and 2, the fteCreateAgent command is used, but for Scenario 4, the agent queue manager QMB is running on the same machine as the agent. Here is an example of an fteCreateAgent command to do this:

 
fteCreateAgent -agentName AG_TEST1_QMB -agentQMgr QMB

After the fteCreateAgent command has run successfully, the file AG_TEST1_QMB_create.mqsc must be used as input to runmqsc for QMB to define the agent's WebSphere MQ objects on QMB.

 
runmqsc QMB < AG_TEST1_QMB_create.mqsc

Configure MSCS queue manager for WebSphere MQ FTE

This scenario does not require a specific installation of WebSphere MQ FTE on the cluster machines, which are used purely as hosts for the WebSphere MQ FTE coordination queue manager. From Install WebSphere MQ FTE Server on the remote machine, a single mqsc script will have been generated (QMA.mqsc). Copy the script to the cluster node currently hosting QMA, and run the script against the queue manager (the queue manager must be running).

 
runmqsc QMA < QMA.mqsc

The script generates the WebSphere MQ Objects required to enable QMA to perform the role of coordination queue manager.

Start the remote agent

Now start the agent AG_TEST1_QMB on the remote machine by using the fteStartAgent command:

 
fteStartAgent –F AG_TEST1_QMB

The –F option forces the agent to run in the foreground in a command window, so that you can see what the agent is doing when the queue manager fails over on the MSCS cluster without having to view the Agent log files. When the agent starts successfully, the following messages appear in the command window:

 
BFGAG0058I: The agent has successfully initialized. 
BFGAG0059I: The agent has been successfully started.

Now use ftePingAgent to confirm that AG_TEST1_QMB is able to communicate with its agent queue manager. Leave the AG_TEST1_QMB running while moving on to the next step.

Simulate a failover on the MSCS cluster

To simulate failover, use the Simulate Failover function provided by the MSCS Failover Management Console. When MSCS initiates a failover, QMA is terminated on the currently active node. AG_TEST1_QMB should continue operating normally, although any transfers in the system will go into recovery. The WebSphere MQ channels between QMB and QMA will stop but will restart again when failover is complete.

Scenario 5: Agent created as a Windows service and started as a generic service within the MSCS queue manager group.

In Scenario 5, the agent AG_TEST1_QMA is part of the MSCS cluster as a generic service, which requires the agent to either be created or migrated to a Windows service, a feature present only in WebSphere MQ FTE V7.0.3 or later. Controlling the agent through the Windows service functionality enables the agent to be cluster aware, which is a great improvement over Scenario 2, since the agent can be controlled and inspected by MSCS using the standard Windows service APIs. Unlike Scenario 2, if the agent ends, MSCS now can detect it and restart the agent (or fail over the queue manager group if configured to do so). Additionally you can manually stop and start the agent using the MSCS administration interface, a feature not possible in Scenario 2. Configuration of Scenario 5 is described in the following steps, which assume that Steps 1.1 and 1.2 (MSCS Configuration and Configuring WebSphere MQ with MSCS) above have been completed.

• Install and configure WebSphere MQ FTE server on both nodes in the cluster
• Create the WebSphere MQ FTE Agent as a Windows service on the first node
• Migrate the WebSphere MQ FTE Agent on the second node to a Windows service
• Put the agent Service under MSCS control
• Simulating failover

Install and configure WebSphere MQ FTE server on both nodes in the cluster

For this scenario, WebSphere MQ FTE is installed locally on each of the nodes, as in Scenario 2. The agent's configuration directory is on a cluster disk tied to the same MSCS group as the agent queue manager (Cluster_Disk1), which can then be moved between the nodes on failover.

Install WebSphere MQ FTE on both nodes in the cluster as in Scenario 1, Section 2.1. However, the configuration directory must be on the shared disk Cluster_Disk 1 managed by MSCS, rather than on a file system local to that node. Additionally, the commands fteSetupCoordination and fteSetupCommands do not need to be run on the second node, because in this scenario the configuration is shared across the nodes.

Create the WebSphere MQ FTE agent as a Windows service on the first node

Before creating the WebSphere MQ FTE agent on the first node, make sure that the WebSphere MQ queue manager QMA is active on the first node. If QMA is not active, use the MSCS Failover Cluster Management console to move the MSCS service mscs-mq01 to nodeA.

Use the fteCreateAgent command to create the agent as a local Windows service on the first node, specifying QMA as the agent queue manager, and the user that the service will be run as. To create a Windows services, you must run the command with Administrator privileges.

 
fteCreateAgent -agentName AG_TEST1_QMA -agentQMgr QMA  -s -su <DOMAIN>/<DOMAINUSER> -sp <DOMAINUSER_PASSWORD>
|-------10--------20--------30--------40--------50--------60--------70--------80--------9|
|-------- XML error:  The previous line is longer than the max of 90 characters ---------|

After the fteCreateAgent command has run successfully, you need to run the generated mqsc file (AG_TEST1_QMA_create.mqsc) against the cluster queue manager (QMA) to define the agent-specific WebSphere MQ objects, as described above in Configure MSCS queue manager for WebSphere MQ FTE.

Open the Windows service administration interface under Administration Tools to verify that the agent has successfully registered as a Windows service. The service "IBM WebSphere MQ FTE agent AG_TEST1_QMA@QMA" should be shown in a stopped state. Start the service, and check the Agent logs for a successful start within the agent configuration directory. Make sure the agent has been stopped before continuing to the second node.

If an agent already exists on the MSCS node, it is possible to migrate this agent to run under the control of a Windows service, which must be done on the second node regardless. These steps are outlined in the following section, and can be applied to an existing agent on node 1 if such a configuration exists.

Migrate the WebSphere MQ FTE agent on the second node to a Windows service

As previously stated, in this scenario both nodes share a WebSphere MQ FTE configuration directory. As far as WebSphere MQ FTE is concerned, the original fteCreateAgent on the first node makes the agent available to whichever machine holds the agent configuration directory. So rather than creating a second instance of the agent, all you need to do is register the existing agent as a local Windows service on the second node, using the fteModifyAgent command.

Firstly use MSCS Failover Cluster Management to move the MSCS queue manager group over to nodeB by moving the MSCS service mscs-mq01 to nodeB. When QMA has restarted on nodeB, register the WebSphere MQ FTE agent as a local Windows service on nodeB, again running the command with Administrator privileges:

 
fteModifyAgent -agentName AG_TEST1_QMA -s 
               -su <DOMAIN>/<DOMAINUSER> 
               -sp <DOMAINUSER_PASSWORD>

The WebSphere MQ objects for AG_TEST1_QMA do not need to be defined a second time, as this was done in the steps for creating the agent on nodeA.

Again, check that the agent service now exists within the local Window services interface on nodeB. Start the agent using the standard Windows service mechanism, and ensure that it logs that it successfully starts in its agent log file within the agent configuration directory. Finally stop the agent through the Windows service control. The service should now show under the Windows services interface on both machines.

Put the agent service under MSCS control

Next, register the agent as a generic service with MSCS. As stated above, registering the agent as a generic service ensures that MSCS will attempt to start the agent when either the agent ends or mscs-mq01 is failed over. the agent only needs to be registered on one of the nodes (whichever is currently hosting the queue manager group and the disk configured to hold the agent configuration directory). The unique Windows service name for the agent is required for this command, and you can find it in the Properties of the agent service on the Windows services interface. This unique identifier is the "Service name" of the agent service, not the "Display Name."

 
cluster.exe /cluster: MyCluster res "MSCS AGENT" /create /group:"mscs-mq01" 
            /type:"Generic Service" /priv ServiceName="fteAgentAG95TEST195QMAQMAE" 
            /priv StartupParameters="C:\Program Files\IBM\WMQFTE\lib\fteService32.exe 
            //RS//fteAgentAG95TEST195QMAQMAE" /AddDep:"Cluster IP Address" 
            /AddDep:"Cluster Disk 1"

Start the agent from the MSCS Failover Management Console by using the start option available on the MSCS generic service configured for the Agent AG_TEST1_QMA. After the agent has started, use the ftePingAgent command to confirm that it is running.

Simulating Failover

To simulate failover, use the "Simulate failover" function provided by the MSCS Failover Management Console. After a short while, MSCS will report that the service mscs-mq01 and all its constituent parts (QMA, Cluster_Disk1 - holding agent configuration, Quorum_Disk, and the IP address) have moved to nodeB and are running. After QMA restarted on nodeB, MSCS will have started the agent AG_TEST1_QMA on nodeB. Use the ftePingAgent command as above to confirm that this is the case.

Looking back on nodeA, the agent will shut down as described above in Scenario 2. However unlike in Scenario 2, as the agent has been shutdown in a controlled manner by MSCS through the Windows service mechanism, it can stop gracefully and log this information to its agent log file before all resources in the queue manager group are moved over to the partner node.

Conclusion

This article has described a number of scenarios in which you can use WebSphere MQ FTE in conjunction with an MSCS environment to enable high availability in your WebSphere MQ FTE network. The article highlighted advantages and drawbacks of the various implementations, and showed how WebSphere MQ FTE V7.0.3 enhances the options available in previous versions.

Resources

• WebSphere MQ resources
  • WebSphere MQ developer resources page
    Technical resources to help you design, develop, and deploy messaging middleware with WebSphere MQ to integrate applications, Web services, and transactions on almost any platform.
  • WebSphere MQ product page
    Product descriptions, product news, training information, support information, and more.
  • WebSphere MQ documentation library
    WebSphere MQ product manuals.
  • WebSphere MQ V7 information center
    A single Web portal to all WebSphere MQ V7 documentation, with conceptual, task, and reference information on installing, configuring, and using WebSphere MQ V7.
  • WebSphere MQ support page
    A searchable database of support problems and their solutions, plus downloads, fixes, and problem tracking.
  • WebSphere MQ public newsgroup
    A non-IBM forum where you can get answers to your WebSphere MQ technical questions and share your WebSphere MQ knowledge with other users.
  • WebSphere MQ SupportPacs
    Downloadable code, documentation, and performance reports for the WebSphere MQ family of products.
  
  
• WebSphere MQ File Transfer Edition (FTE) resources
  • WebSphere MQ FTE product page
    Product descriptions, product news, training information, support information, and more.
  • WebSphere MQ FTE Information Center
    A single Web portal to all WebSphere MQ FTE V7 documentation, with conceptual, task, and reference information on installing, configuring, and using WebSphere MQ FTE
  • WebSphere MQ FTE forum
    Get answers to your WebSphere MQ FTE technical questions and share your WebSphere MQ FTE knowledge with other users.
  • Download a free trial version of WebSphere MQ FTE V7
    A 90 day, full featured, no-charge trial of WebSphere MQ FTE V7
  • WebSphere MQ FTE blog on developerWorks
    A forum where you can interact with the IBM team that develops WebSphere MQ FTE.
  • Getting started with WebSphere MQ FTE V7
    This developerWorks article takes you through basic concepts and tasks with WebSphere MQ FTE V7
  • IBM Redbook: Getting started with WebSphere MQ FTE V7
    Similar to the preceding article, but in much greater depth and with comprehensive examples in the IBM Redbook format.
  • IBM Redguide: Managed file transfer for SOA using WebSphere MQ FTE
    This IBM Redguide covers business as well as technical aspects of managed file transfer using WebSphere MQ FTE in an SOA environment.
  • IBM Redpaper: WebSphere MQ FTE solution overview
    This IBM Redpaper describes sample solutions and scenarios with WebSphere MQ FTE.
  
  
• IBM WebSphere resources
  • developerWorks WebSphere developer resources
    Technical information and resources for developers who use WebSphere products. developerWorks WebSphere provides product downloads, how-to information, support resources, and a free technical library of more than 2000 technical articles, tutorials, best practices, IBM Redbooks, and online product manuals.
  • developerWorks WebSphere application connectivity developer resources
    How-to articles, downloads, tutorials, education, product info, and other resources to help you build WebSphere application connectivity and business integration solutions.
  • developerWorks WebSphere business process management developer resources
    WebSphere BPM how-to articles, downloads, tutorials, education, product info, and other resources to help you model, assemble, deploy, and manage business processes.
  • developerWorks WebSphere SOA and Web services developer resources
    How-to articles, downloads, tutorials, education, product info, and other resources to help you design and build WebSphere SOA and Web services solutions.
  • Most popular WebSphere trial downloads
    No-charge trial downloads for key WebSphere products.
  • WebSphere forums
    Product-specific forums where you can get answers to your technical questions and share your expertise with other WebSphere users.
  • WebSphere on-demand demos
    Download, watch, and learn what WebSphere products and WebSphere-related technologies can do for your company.
  • developerWorks WebSphere weekly newsletter
    The developerWorks newsletter gives you the latest articles and information only on those topics that interest you. In addition to WebSphere, you can select from Java, Linux, Open source, Rational, SOA, Web services, and other topics. Subscribe now and design your custom mailing.
  • WebSphere-related books from IBM Press
    Convenient online ordering through Barnes & Noble.
  • WebSphere-related events
    Conferences, trade shows, Webcasts, and other events around the world of interest to WebSphere developers.
  
  
• IBM developerWorks resources
  • Trial downloads for IBM software products
    No-charge trial downloads for selected IBM® DB2®, Lotus®, Rational®, Tivoli®, and WebSphere® products.
  • developerWorks blogs
    Join a conversation with developerWorks users and authors, and IBM editors and developers.
  • developerWorks Webcasts
    Free technical sessions by IBM experts that can accelerate your learning curve and help you succeed in your most difficult software projects. Sessions range from one-hour Webcasts to half-day and full-day live sessions in cities worldwide.
  • developerWorks podcasts
    Listen to interesting and offbeat interviews and discussions with software innovators.
  • developerWorks on Twitter
    Check out recent Twitter messages and URLs.
  • IBM Education Assistant
    A collection of multimedia educational modules that will help you better understand IBM software products and use them more effectively to meet your business requirements.
  
  

About the authors

Phil Bareham is a Senior IT Specialist with ten years experience at the IBM Software Lab in Hursley, United Kingdom. You can contact Phil at phil_bareham@uk.ibm.com.

Laurence Bonney is a software engineer at IBM Hursley Labs in the United Kingdom. He works as the Technical Team Leader of the test team working on the IBM WebSphere MQ JMS product. In his spare time he plays guitar (badly), goes surfing as much as his vacation will allow, and plays video games. You can reach Laurence at bonneyl@uk.ibm.com.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Configuring MSCS and WebSphere MQ
• WebSphere MQ FTE and MSCS scenarios
• Scenario 1: Agent started through a WebSphere MQ service outside MSCS control
• Scenario 2: Agent started as a Generic Application within the MSCS queue manager group
• Scenario 3: Agent remote to MSCS cluster accessing MSCS agent queue manager over TCP/IP
• Scenario 4: Agent remote to MSCS, locally bound to its agent queue manager, accessing MSCS clustered queue manager
• Scenario 5: Agent created as a Windows service and started as a generic service within the MSCS queue manager group.
• Conclusion
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: WebSphere MQ File Transfer Edition
• Buy: WebSphere MQ File Transfer Edition

Dig deeper into WebSphere on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers