3.5 Installing and Configuring the MTA and the POA in a Cluster

After you have created a new domain and/or post office, you are ready to install and configure the GroupWise agents. Complete all the tasks below if you are setting up a new GroupWise system or if you have created a new GroupWise volume where you want to install the agent software:

Under some circumstances, the agent software has already been installed and you simply need to create a new startup file specific to the new domain or post office. For example:

In these circumstances, follow the instructions in Setting Up New Instances of the Agents without Installing the Agent Software instead of completing the tasks above.

3.5.1 Installing the Agent Software in a Cluster

To install the MTA and the POA:

  1. Map a drive to the GroupWise volume for the domain (Agent Clustering Worksheet item 2) or the post office (Agent Clustering Worksheet item 5).

    The GroupWise volume name will be cluster_volume. For assistance with mapping a drive to a cluster-enabled volume, see Configuring Short Name Resolution.

  2. If you selected vol:\system on GroupWise volume as the agent installation location (under Agent Clustering Worksheet item 1), create the vol:\system directory on the GroupWise volume accessed in Step 1.

    or

    If you selected sys:\system on each node, decide which node you will install the agents to first.

  3. Start the Agent Installation program, following the steps provided in Installing the NetWare Agent Software in Installing GroupWise Agents in the GroupWise 7 Installation Guide.

  4. Install the NetWare agents, keeping in mind the following cluster-specific details:

    • Use the NetWare Agent Clustering Worksheet that you filled out in Planning the NetWare Agent Installation to fill in the fields during the agent installation process.

    • In the Installation Path dialog box, be sure to browse through the drive you mapped in Step 1 to the location you chose in Step 2 above. Also select Configure GroupWise Agents for Clustering.

    • In the Domains / Post Offices dialog box, click Add for each domain and post office that the agents will service. In the Path to Database field, be sure to browse through the drive you mapped in Step 1 above to the domain directory or the post office directory. In the HTTP Port field, specify the cluster-unique HTTP port planned for each agent (under Agent Clustering Worksheet items 4 and 7).

    • In the Installation Complete dialog box, do not select Launch GroupWise Agents Now. You will configure the agents to launch in protected mode later.

  5. If you need to install the agents to sys:\system on multiple nodes in the cluster:

    1. Repeat Step 4, mapping new drives as needed.

    2. If you marked Yes for Consolidate Multiple Startup Files on GroupWise Volume? (under Agent Clustering Worksheet item 1), copy one complete set of agent startup files and the grpwise.ncf file to the planned location, then delete all agent startup files, as well as the grpwise.ncf file, from the sys:\system directories to avoid future confusion.

      The grpwise.ncf file includes a load command for each instance of each agent. You will use this information later when you create the load and unload scripts for the volume resources.

  6. Continue with Editing Clustered Agent Startup Files.

3.5.2 Editing Clustered Agent Startup Files

By default, the Agent Installation program creates agent startup files in the agent installation directory. Each MTA startup file is named after the domain it services, with a .mta extension. Each POA startup file is named after the post office it services, with a .poa extension.

Because you selected Configure GroupWise Agents for Clustering during installation, the Agent Installation program set the MTA /home startup switch and the POA /home startup switch using the format:

volume:\directory

so that the startup files are valid no matter which node the agents are currently running on.

The Agent Installation program also adds a /cluster startup switch to POA startup files to ensure that GroupWise clients detect the clustering environment and try more persistently to reconnect in a failover, failback, or migration situation.

One additional manual modification of POA startup files is required for robust functionality in a clustering environment. Uncomment the /ip startup switch and provide the secondary IP address of the GroupWise volume where the post office is located (Agent Clustering Worksheet item 7). This information is available to the POA in its eDirectory object properties. However, in some failover situations, reconnection to the MTA is improved when the information is immediately available to the POA in its startup file.

If you are running the POA in protected memory and your version of NetWare requires it, add the /user and /password startup switches (under Agent Clustering Worksheet item 8) in order to provide a user name and password that the POA can use to access its post office volume.

If the POA needs to access a remote document storage area, add the /user and /password startup switches (under System Clustering Worksheet item 12) in order to provide a user name and password that the POA can use to access the volume where the document storage area resides. As an alternative to startup switches, you can assign the POA object all rights except Supervisor and Access control, as long as the remote document storage area is located in the same tree with the post office.

If you have connection problems between the MTA and the POA, you can use the /user and /password startup switches in the MTA startup file as well.

3.5.3 Configuring the GroupWise Volume Resource to Load and Unload the Agents

The properties of the Volume Resource object define how the GroupWise volume functions within the cluster, how NLM™ programs are loaded and unloaded, and how failover and failback situations are handled. At this point, you might have one volume resource with a domain and post office on it, or you might have two volume resources, one for the domain and one for the post office. Complete the following tasks for each volume resource:

Modifying the Volume Resource Load Script for the Agents

The volume resource load script executes whenever the GroupWise volume comes online.

To set up the load script:

  1. In ConsoleOne, browse to and select the Cluster object.

    If necessary, click View > Console View to display its contents.

  2. Right-click the Volume Resource object (volume_SERVER), then click Properties > Load to display the default volume resource load script for the GroupWise volume.

  3. Make the following changes to the default load script:

    • Remove the trustmig command. It is not necessary to migrate trustees for a GroupWise volume. Removing this line helps the load script to execute faster.

    • On NetWare 5.1, if you selected SLP as a short name resolution method, add the cvsbind add command for the GroupWise volume to the load script.

      cvsbind add cluster_volume_SERVER IP_address
      
    • If you selected vol:\system on GroupWise volume as the agent installation location (Agent Clustering Worksheet item 1), add a search add command to add the new vol:\system directory to the server search path.

      search add volume:\system
      
    • If you selected sys:\system on each node as the installation location (Agent Clustering Worksheet item 1) but you are storing the agent startup files on the GroupWise volume, add that location to the server search path.

    • If you marked No under Load Agents in Protected Memory? (Agent Clustering Worksheet item 8), add the following abend recovery options:

      set auto restart after abend = 2
      set auto restart after abend delay time = 0
      set auto restart down timeout = 60
      set developer option = off
      

      These settings provide the best possible handling of GroupWise databases in the event that an abend should occur within the cluster when the agents are not running in protected memory.

    • Transfer the agent load commands from the grpwise.ncf file into the load script. Use Ctrl+C to copy and Ctrl+V to paste text into the load script page. Then delete or rename the grpwise.ncf file to avoid future confusion.

      load volume:\system\agent.nlm @startup_file
      
    • If you marked Yes under Load Agents in Protected Memory? (Agent Clustering Worksheet item 8), add the address space parameter to the agent load commands to specify the protected address space for each agent. Add a protection restart command for each address space name.

      load address space=addr_space_name
                              volume:\system\agent.nlm @startup_file
      protection restart name
      

    The result would look similar to the following example:

    Modified load script

    NOTE:The set commands are needed in the load script only when the agents are not running in protected memory. The address space parameters are needed in the load commands only when the agents are running in protected memory.

  4. Click Apply to save the load script.

  5. If necessary, click OK to confirm that you must offline and then online the volume resource in order for the changes to take effect.

  6. Continue with Modifying the Volume Resource Unload Script for the Agents.

Modifying the Volume Resource Unload Script for the Agents

The volume resource unload script executes whenever the GroupWise volume goes offline. Programs should be unloaded in the reverse order of how they were loaded. This ensures that supporting programs are not unloaded before programs that rely on them in order to function properly.

To set up the unload script:

  1. In ConsoleOne, in the properties pages for the Volume Resource object (volume_SERVER), click Unload to display the default volume resource unload script.

  2. Make the following changes to the default unload script:

    • If you marked Yes under Load Agents in Protected Memory? (Agent Clustering Worksheet item 8), add an unload address space command for each address space. Add an unload kill address space command to ensure that the address space is completely cleaned up.

      unload address space=addr_space_name
      unload kill address space=addr_space_name
      

      If your system seems to be trying to kill the address space before the GroupWise agents have been completely unloaded, resulting in the agents hanging in the unloading state, load the delay.nlm program and set a delay of several seconds before issuing the unload kill address space command to allow the GroupWise agents adequate time to unload completely. The length of the delay varies from system to system; ten seconds is a good starting place.

      unload address space=addr_space_name
      load delay.nlm
      delay 10
      unload kill address space=addr_space_name
      
    • If you marked No under Load Agents in Protected Memory? (Agent Clustering Worksheet item 8), create an unload command parallel to each load command that you placed in the load script.

      unload agent.nlm
      
    • On NetWare 5.1, if you selected SLP as a short name resolution method, add the cvsbind del command for the GroupWise volume to the unload script.

      cvsbind del cluster_volume_SERVER IP_address
      
    • Remove the trustmig command just like you did in the load script.

    The result would look similar to the following example:

    Modified unload script
  3. Click Apply to save the unload script.

  4. If necessary, click OK to confirm that you must offline and then online the volume resource in order for the changes to take effect.

  5. Continue with Setting the Failover Path and Policies for the Agents.

Setting the Failover Path and Policies for the Agents

To modify the failover path and policies for a GroupWise volume resource:

  1. In ConsoleOne, in the properties pages for the Volume Resource object (volume_SERVER), click Nodes to display the default failover path for the GroupWise volume resource.

    Volume resource failover path
  2. Arrange the nodes in the cluster into the desired failover path for the domain or post office volume (under Agent Clustering Worksheet items 3 or 6).

  3. Click Apply to save the failover path.

  4. Click Policies to display the default start, failover, and failback policies.

    Default start, failover, and failback policies

    The default policy settings are often appropriate. By default, a volume resource:

    • Fails over automatically if the node it is running on fails

    • Starts automatically on the next node in its failover path

    • Continues running at its failover location, even after its most preferred node is again available

    If you are considering changing these defaults, see the section about failover and failback modes in the cluster documentation for your version of NetWare, as listed in Section 1.0, Introduction to GroupWise 7 and Novell Cluster Services on NetWare.

  5. Click OK when you are finished editing the GroupWise volume resource properties.

  6. Skip to Section 3.6, Testing Your Clustered GroupWise System.

3.5.4 Setting Up New Instances of the Agents without Installing the Agent Software

There are two steps to setting up new instances of the agents without installing the agent software:

Creating New Startup Files

Each MTA startup file is named after the domain it services, with a .mta extension. Each POA startup file is named after the post office it services, with a .poa extension. If the existing agent software is located in the vol:\system directory of a GroupWise volume, the startup files are there as well. If the existing agent software is located in multiple sys:\system directories, the startup files might be located there as well, or they might be in a directory on a GroupWise volume.

To create a new startup file without installing the agent software:

  1. Make a copy of an existing startup file and name it after the domain or post office that will be serviced by the agent.

  2. Edit the setting of the /home startup switch to point to the location of the new domain directory or post office directory. Be careful to maintain the syntax of the original line.

  3. Scroll down through the startup file looking for other active (not commented out) startup switches, then modify them as needed for the new agent.

    For example, you might find that the /httpport switch is active and needs to be changed to a cluster-unique port number for the new agent.

  4. Save the new startup file.

  5. Continue with Modifying Existing Load and Unload Scripts.

Modifying Existing Load and Unload Scripts

The agent startup file names are part of the load commands found in GroupWise volume resource load scrips.

If you created the new domain and/or post office on a new GroupWise volume, skip back to Configuring the GroupWise Volume Resource to Load and Unload the Agents for instructions to create new load and unload scripts.

If you created the new domain and/or post office on an existing GroupWise volume, most of the configuration of the volume resource has already been done. You just need to add new load and unload commands to the existing scripts. Continue with the steps below:

To modify existing load and unload scripts:

  1. In ConsoleOne, browse to and select the Cluster object.

    If necessary, click View > Console View to display its contents.

  2. Right-click the Volume Resource object (volume_SERVER), then click Properties > Load to display the volume resource load script for the GroupWise volume.

  3. Following the pattern of the existing load commands, add load commands for the new instances of the agents you are setting up. Use Ctrl+C to copy and Ctrl+V to paste lines in the load script page.

    The results would be similar to the following example:

    Sample modified load commands
  4. Click Apply to save the modified load script.

  5. Click Unload

  6. Add corresponding unload commands for the new instances of the agents.

    Sample modified unload commands
  7. Click Apply to save the modified unload script.

    You might want to review other properties of the Volume Resource object, such as the failover path on the Nodes page and the failover/failback/migration procedures on the Policies page, in light of the fact that an additional domain and/or post office now resides on the GroupWise volume.

  8. Change other Volume Resource properties as needed.

  9. Click OK to save the modified properties.

  10. In the Cluster State View, take the GroupWise volume offline and then bring it online again to test the new startup files and the modified load and unload scripts. If you need assistance with these tasks, see Section 3.6, Testing Your Clustered GroupWise System.