Configuring WebSphere MQ File Transfer Edition with Microsoft Cluster Server

This article shows you how to configure WebSphere MQ File Transfer Edition for use with Microsoft Cluster Service (MSCS). MSCS enables you to put servers into a cluster to provide high availability to applications and data. If a server fails, work is transferred to another server in the cluster with little interruption of service to clients connected to the cluster.

Phil J. Bareham (phil_bareham@uk.ibm.com), Senior IT Specialist, Worldwide Technology Practise, IBM Software Services for WebSphere

Photo of Phil BarehamPhil 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 (bonneyl@uk.ibm.com), WebSphere MQ JMS Test Team Lead, IBM

Photo of Laurence BonneyLaurence 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.



19 January 2011

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:

Figure 1. Typical two-server MSCS cluster
Typical two-server MSCS cluster

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:

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:

Listing 1.1.1. Example 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:

Listing 1.1.2. Defining the coordination queue manager
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:

Listing 1.1.3. Defining coordination queue manager WebSphere MQ Objects
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:

Listing 1.1.4. Defining the command queue manager
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:

Listing 1.2.1. Creating agent on the first node
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:

Listing 1.2.2. Defining agent queue manager WebSphere MQ Objects
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:

Listing 1.3.1. Creating agent on the second node
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:

Listing 1.4.1. Defining WebSphere MQ Service to start the agent
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:

Listing 1.4.2. Pinging the agent
ftePingAgent AG_TEST1_QMA

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

Listing 1.4.3. Successful ftePingAgent example
> 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:

Listing 1.4.4. Unsuccessful ftePingAgent example
> 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:

Listing 1.4.5. Failure to start agent
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:

Listing 1.5.1. Agent losing connectivity to its queue manager
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:

Listing 1.5.2. Agent queue manager no longer defined 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:

Listing 1.5.3. Agent continuing to loop in recovery
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

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.

Listing 2.3.1. Defining start agent MSCS resource
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

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:

Listing 3.3.1. Defining the coordination queue manager
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:

Listing 3.1.2. Defining the command queue manager
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:

Listing 3.2.1. Creating the agent
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

Mixing scenario concepts

You can develop a configuration that combines Scenario 3 with Scenario 1 or 2, such that the system has agents running on remote machines connecting to a queue manager under MSCS control, alongside agents running on the MSCS nodes under MSCS control, and then transfer between them. This setup is a concatenation of this scenario with some of the previous scenario concepts and is perfectly valid.

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):

Listing 3.3.1. Running MQSC scripts against MSCS queue manager
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:

Listing 3.4.1. Starting the remote Agent
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:

Listing 3.4.2. Output from a successfully started agent
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:

Listing 3.5.1. Remote agent output from queue manager going offline
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:

Listing 3.5.2. Remote agent output from queue manager coming online
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

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:

Listing 4.2.1. WebSphere MQ FTE client installation with a bindings configured agent
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:

Listing 4.2.2. Defining the coordination queue manager
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.

Listing 4.2.3. Defining 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:

Listing 4.3.1. Creating the locally bound agent
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.

Listing 4.3.2. Generating agent queue manager objects
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).

Listing 4.4.1. Generating coordination queue manager objects
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:

Listing 4.5.1. Starting the locally bound agent
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:

Listing 4.5.2. Output from a successfully started agent
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

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.

Listing 5.2.1. Creating a WebSphere MQ FTE V7.0.3 agent as a Windows service

Click to see code listing

Listing 5.2.1. Creating a WebSphere MQ FTE V7.0.3 agent as a Windows service

fteCreateAgent -agentName AG_TEST1_QMA -agentQMgr QMA  -s -su <DOMAIN>/<DOMAINUSER> -sp <DOMAINUSER_PASSWORD>

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:

Listing 5.3.1. Migrating WebSphere MQ FTE V7.0.3 agent to a Windows service
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."

Listing 5.4.1. Defining WebSphere MQ FTE agent as an MSCS generic service
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

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=618443
ArticleTitle=Configuring WebSphere MQ File Transfer Edition with Microsoft Cluster Server
publish-date=01192011