1.6 Implementing the Internet Agent in a Linux Cluster

You should already have set up at least a simple GroupWise system, as described in Planning GroupWise in a Linux Cluster and Creating a New GroupWise System to Work with OES Cluster Services. As part of this process, you filled out the System Clustering Worksheet. If you do not have access to the filled-out worksheet, print the worksheet now and fill in the clustering information as it currently exists on your system. You need this information as you implement the Internet Agent (GWIA) in a cluster.

1.6.1 Planning the Internet Agent in a Linux Cluster

A major system configuration difference between the GWIA in a clustering environment and the GWIA in a regular environment is that you need to create a separate domain to house the GWIA in the clustering environment.

The Internet Agent Clustering Worksheet lists the information you need as you set up the GWIA in a clustering environment. You should print the worksheet and fill it out as you complete the tasks listed below:

Planning a Domain for the GWIA

The considerations involved in planning a domain for the GWIA are much the same as planning any other domain. In preparation, review Planning a Domain; then, print and fill out the Primary Domain Worksheetin the GroupWise Installation Guide.

Keep in mind the following cluster-specific details:

  • When you specify the location for the domain directory on the Domain Worksheet, remember that it is on a GroupWise partition, not on the node where you running the GroupWise Installation program. This location is referred to as the GWIA partition because it is where the GWIA message queues are located.

  • Do not concern yourself with the GroupWise agent information on the Domain Worksheet. You can stop at MTA Settings. MTA planning will be discussed later.

When you have completed the Domain Worksheet, transfer the key information from the Domain Worksheet to the Internet Agent Clustering Worksheet.

INTERNET AGENT CLUSTERING WORKSHEET

Under Item 1: GroupWise Partition for the GWIA, transfer the domain location to the Internet Agent Clustering Worksheet.

Under Item 2: GWIA Domain Name, transfer the domain name and database directory to the Internet Agent Clustering Worksheet.

IMPORTANT:Do not create the new domain until you are instructed to do so in Creating a Domain for the GWIA.

Selecting the GWIA Partition and Secondary IP Address

As with the MTA, the POA, and the DVA, the GWIA needs a secondary IP address that remains the same no matter which node in the cluster it is running on. You can place the GWIA and its domain on a GroupWise partition where a domain or post office already reside, which means that the GWIA shares the same secondary IP address as that domain or post office and fails over along with that domain or post office. Or you can place the GWIA and its domain on its own GroupWise partition, which means that it has its own secondary IP address and fails over independently.

INTERNET AGENT CLUSTERING WORKSHEET

Under Item 1: GroupWise Partition for GWIA, specify the secondary IP address for the GWIA partition.

Under Item 5: MTA Network Information, copy the same secondary IP address.

Under Item 6: GWIA Network Information, copy the same secondary IP address.

IMPORTANT:You must configure the GWIA to bind exclusively to the secondary IP address. OES Cluster Services uses Postfix to send cluster email alerts using the primary IP address. Postfix and the GWIA both default to port 25. A conflict results unless you configure the GWIA so that it does not use the primary IP address. Instructions are provided in Forcing Use of the GWIA Secondary IP Address.

Determining an Appropriate Failover List for the Linux GWIA

By default, a GroupWise partition is configured to have all nodes in the cluster in its failover list, organized in ascending alphanumeric order. Only one node at a time can have a particular GroupWise partition mounted and active. If a GroupWise partition’s preferred node fails, the partition fails over to the next node in the failover list. You should customize the failover list for each GroupWise partition based on the fan-out-failover principle.

As with the MTA, the POA, and the DVA, you need to decide which nodes in the cluster are appropriate locations for the GWIA partition to fail-over to. You must install the GWIA software on all of the nodes where you want the GWIA to be able to fail-over. For a review of failover lists, see Determining Appropriate Failover Lists for the Linux Agents, which describes the issues in the context of planning installations for the other GroupWise agents.

INTERNET AGENT CLUSTERING WORKSHEET

Under Item 3: GWIA Failover List, list the nodes that you want in the GWIA partition failover list.

Cluster Resource Information for the Linux GWIA

A cluster resource is a shared partition, secondary IP address, application, service, Web server, and so on, that can function successfully anywhere in the cluster. Cluster resources include the GroupWise agents and the Messenger agents.

INTERNET AGENT CLUSTERING WORKSHEET

Under Item 4: Cluster Resource Mount Point, list the mount point for the GroupWise partition where the GWIA domain is located.

Preparing DNS for the Clustered Linux GWIA

In order for the GWIA partition to be recognized on your network, DNS must have an MX record that includes the hostname corresponding to the secondary IP address of the GWIA partition. A DNS A record associates the secondary IP address with the hostname.

Preparing Your Firewall for the Clustered Linux GWIA

The GWIA receives incoming messages on the secondary IP address of the GWIA partition. Your firewall configuration must be modified to allow inbound TCP/IP traffic from the Internet to the GWIA secondary IP address on the following standard ports:

Protocol

Standard Port

IMAP4

143

LDAP

389

POP3

110

SMTP

25

By default, the GWIA sends outgoing messages on the primary IP address of the server where it is running. If you decide to use this default configuration, your firewall must be configured to allow outbound TCP/IP traffic from all nodes in the GWIA partition failover list. However, because Postfix uses the primary IP address for sending cluster email alerts, the default GWIA configuration is not recommended. To avoid a port conflict, configure the GWIA to bind to the secondary IP address, as described in Forcing Use of the GWIA Secondary IP Address.

If the GWIA has a large number of nodes on its failover list, you can configure the GWIA to send outgoing messages to a relay host, which then sends them out through the firewall using its own IP address rather than the address of the particular node where the GWIA was running. This reduces the amount of modification to your firewall required to set up the GWIA. However, if the relay host goes down, outgoing messages are delayed.

In preparation for installing the GWIA, configure your firewall as needed to handle the GWIA’s use of primary and secondary IP addresses when sending and receiving messages.

Planning the Linux GWIA Installation

IMPORTANT:Do not install the GWIA software until you are instructed to do so in Setting Up the GWIA in a Linux Cluster.

1.6.2 Setting Up the GWIA in a Linux Cluster

You should already have reviewed Planning the Internet Agent in a Linux Cluster and filled out the Internet Agent Clustering Worksheet. You are now ready to complete the following tasks to set up the GWIA in a clustering environment:

Creating a Domain for the GWIA

The GWIA domain will be a secondary domain. To create it, follow the instructions in Creating a New Secondary Domain in a Linux Cluster, taking your information from the GWIA Clustering Worksheet, rather than the System Clustering Worksheet, and then return to this point.

Do not create any post offices in the GWIA domain.

After you have created the domain, continue with Configuring the Linux GWIA in a Cluster.

Configuring the Linux GWIA in a Cluster

After you have created a domain for the GWIA , you are ready to configure the GWIA.

Configuring the Clustered Linux GWIA for SSL

If you plan to enable SSL, as described in Securing Internet Access with TLS Connections to the GWIA in the GroupWise Administration Guide, you must make the SSL certificate file and key file available to the GWIA in the cluster. The default locations for the SSL certificate file and key file are on the cluster nodes along with the GroupWise software, rather than being located with the domain and post office on one or more GroupWise partitions. To avoid having multiple copies of these files in multiple locations, you should set the locations in the Administration Console.

  1. On the GWIA partition, create the directory where you want to store the certificate and key file required for SSL.

  2. Copy the certificate file and key file into the new directory.

    If you need assistance obtaining these files, see Encryption and Certificates in the GroupWise Administration Guide.

  3. Continue by following the instructions in Securing Internet Access with TLS Connections to the GWIA in the GroupWise Administration Guide.

  4. Continue with Configuring the Linux GWIA Cluster Resource to Load and Unload the GWIA and Its MTA.

Configuring the Linux GWIA Cluster Resource to Load and Unload the GWIA and Its MTA

The properties of the Cluster Resource object define how the GWIA partition functions within the cluster, how the GWIA is loaded and unloaded, and how failover and failback situations are handled. Complete the following tasks for the GWIA cluster resource:

Modifying the Cluster Resource Load Script for the Linux GWIA and Its MTA

The cluster resource load script executes whenever the GWIA cluster resource comes online.

To set up the load script in iManager:

  1. Expand Clusters, and then click Cluster Options.

  2. In the Cluster field, browse to the Cluster object where the GWIA cluster resource is located.

  3. Click the Cluster object to display the cluster resources that belong to the cluster.

  4. Select the GWIA cluster resource that you created when you set up the GWIA partition, and then click Details.

  5. Click Scripts > Load Script.

  6. (Conditional) If this is a traditional Linux volume, use a load script similar to the following example, depending on the configuration of your cluster and nodes. This sample cluster load script performs the following actions:

    • Establishes what to do for certain error conditions

    • Creates the GroupWise agent services (if they do not already exist)

    • Starts the GroupWise Admin Service listeners with clustering enabled for the MTA

    • Starts the MTA and GWIA (in that order)

      #!/bin/bash
      ./opt/novell/ncs/lib/ncsfuncs
      exit_on_error nss /poolact=DOM
      exit_on_error ncpcon mount DOM=254
      exit_on_error add_secondary_ipaddress 151.155.136.248
      exit_on_error ncpcon bind --ncpservername=DOM --ipaddress=151.155.136.248
      exit_on_error novcifs --add '--vserver=".cn=DOM.ou=servers.o=novell.t=GW14-TREE."'
                            --ip-addr=151.155.136.248
      # Start gwadmin service
      exit_on_error /etc/init.d/grpwise start gwadminservice
      #create agent services
      exit_on_error /opt/novell/groupwise/admin/gwsc -i /media/nss/DOM/utah
      exit_on_error /opt/novell/groupwise/admin/gwsc -i /media/nss/DOM/utah/wpgate/gwia
      #start admin service listeners
      exit_on_error /opt/novell/groupwise/admin/gwadmin-ipc start utah cluster
      #start GroupWise agents
      exit_on_error /etc/init.d/grpwise start utah
      exit_on_error /etc/init.d/grpwise start gwia.utah
      exit 0
    1. In the define IP address section, specify the secondary IP address of the GWIA partition (Internet Agent Clustering Worksheet item 1).

    2. In the define filesystem type section, specify the filesystem type that is in use in use on the nodes in the cluster (System Clustering Worksheet item 5).

    3. In the define mount point section, specify the mount point directory in use for the nodes in the cluster (System Clustering Worksheet item 5).

    4. In the start service section, provide the commands to start the MTA first, following by the GWIA.

  7. Click OK to save the load script.

Modifying the Cluster Resource Unload Script for the Linux GWIA and Its MTA

The cluster resource unload script executes whenever the GWIA cluster resource 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.

  1. On the iManager Cluster Resource Properties page of the GWIA cluster resource, click Scripts > Unload Script.

  2. (Conditional) If this is a traditional Linux volume, use an unload script similar to the following example, depending on the configuration of your cluster and nodes. This sample cluster unload script performs the following actions:

    • Stops the GroupWise Admin Service listeners for the MTA

    • Stops the MTA and GWIA (in that order)

    • Lists error conditions that can be ignored

    #!/bin/bash
    . /opt/novell/ncs/lib/ncsfuncs
    # Stop admin service listeners
    ignore_error /opt/novell/groupwise/admin/gwadmin-ipc stop utah
    # Stop GroupWise agents
    ignore_error /etc/init.d/grpwise stop utah
    ignore_error /etc/init.d/grpwise stop gwia.utah
    ignore_error novcifs 
                 --remove '--vserver=".cn=DOM.ou=servers.o=novell.t=GW14-TREE."' 
                 --ip-addr=151.155.136.248
    ignore_error ncpcon unbind --ncpservername=DOM --ipaddress=151.155.136.248
    ignore_error del_secondary_ipaddress 151.155.136.248
    ignore_error nss /pooldeact=DOM
    exit 0
    1. In the request service stop section, provide the commands to stop the GWIA first, followed by the MTA.

    2. In the stop service otherwise section, adjust the sleep command as needed so that the agents can shut down normally on your system without being inadvertently killed by the pkill command the follows.

    3. In the define IP address section, specify the secondary IP address of the GWIA partition.

    4. In the define mount point section, specify the mount point directory in use for the nodes in the cluster.

    5. (Conditional) If you are running the GroupWise High Availability (gwha) service, stop it before the script stops the agents, and then start it again at the end of the unload script.

      This prevents the GroupWise High Availability service from trying to restart the agents while the script is trying to stop them.

      Add the following section before the request service stop section:

      # Temporarily disable the gwha service under xinetd
      ignore_error /sbin/chkconfig -s gwha off
      ignore_error kill -HUP `pidof xinetd`

      Add the following section before the return status section:

      # Restart the gwha service under xinetd
      ignore_error /sbin/chkconfig -s gwha on
      ignore_error kill -HUP `pidof xinetd`
  3. Click OK to save the unload script.

Setting the Failover List and Policies for the Linux GWIA and Its MTA
  1. On the iManager Cluster Resource Properties page of the GWIA cluster resource, click General.

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

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

    • Starts automatically on the next node in its failover list

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

      If you are considering changing these defaults, see the OES Cluster Services for Linux Administration Guide for your version of OES Linux.

  2. Under Preferred Nodes, arrange the nodes in the cluster into the desired failover list for the GWIA (Internet Agent Clustering Worksheet item 3).

  3. Click OK.

Enabling Internet Addressing for Your Clustered GroupWise System

Setting up Internet addressing for a clustered GWIA is no different from setting it up for an GWIA in any other environment. Follow the instructions in Configuring Internet Addressing in the GroupWise Administration Guide, and then return to this point.

Forcing Use of the GWIA Secondary IP Address

OES Cluster Services uses Postfix to send cluster email alerts using the primary IP address. Postfix and the GWIA both default to using port 25. You must configure the GWIA to bind exclusively to the secondary IP address in order to avoid a port conflict between Postfix and the GWIA.

  1. Click the GWIA object in the GroupWise Administration Console.

  2. Navigate to GroupWise tab > Agent Settings.

  3. In the Host Name field under Network Address, provide the secondary IP address (Internet Agent Clustering Worksheet item 1) for the GWIA to use for sending outgoing messages.

  4. Select Bind Exclusively to Host Name.

  5. Click OK.

  6. Continue with Verifying GWIA Object Settings.

Verifying GWIA Object Settings

During installation of the GWIA, the GWIA object should have been configured correctly. However, it can be helpful to verify certain cluster-specific information in order to familiarize yourself with the configuration of a clustered GWIA.

Accessing GWIA Object Settings

To access GWIA object settings:

  1. Browse to and select the GWIA object in the Administration Console in order to display its contents.

  2. Continue with Verifying the Reference to the GWIA Cluster Resource.

Verifying the Reference to the GWIA Cluster Resource

In the GWIA object settings:

  1. Click SMTP/MIME > Settings.

  2. Verify the contents of the Hostname/DNS “A Record” Name field.

    This field displays the hostname as currently configured in DNS. It should display the hostname that corresponds to the secondary IP address of the GWIA cluster resource. For more information, see Preparing DNS for the Clustered Linux GWIA.

  3. Make changes if necessary.

  4. Continue with Verifying the Reference to the Mount Point Directory.

Verifying the Reference to the Mount Point Directory

In the GWIA object settings:

  1. Select the Server Directories tab.

  2. Verify that the displayed directories match the mount point directory and the domain directory.

  3. Make changes if necessary.

1.6.3 Testing the Internet Agent in a Linux Cluster

After you have configured the GWIA cluster resource, you can test the load and unload scripts by bringing the cluster resource online and taking it offline again.

  1. In iManager, expand Clusters, and then click Cluster Manager.

  2. Browse to the Cluster object to display the current cluster state.

  3. (Conditional) If the new GWIA cluster resource shows Offline in the State column, click the new GWIA cluster resource, and then click Online.

    After a moment, the GWIA cluster resource displays Running in the State column.

  4. At the server where the GWIA is starting, use the following command to see that the GWIA has started:

    /etc/init.d/grpwise status domain.gwia
  5. Select the new GWIA cluster resource, and then click Offline.

    The State column for the GWIA cluster resource returns to Offline.

  6. Use the same command that you used in Step 4 to verify that the GWIA has stopped.

  7. Repeat Step 3 whenever you are ready to bring the new GWIA cluster resource online permanently.

  8. Continue with Managing Your Clustered GroupWise System on Linux.

1.6.4 Managing the Internet Agent in a Linux Cluster

After you have installed the GWIA in a cluster, you should consider some long-term management issues.

Updating GroupWise Objects with Cluster-Specific Descriptions

After installing the GWIA in your clustered GroupWise system, while the cluster-specific information is fresh in your mind, you should record the cluster-specific information as part of the GroupWise objects in the GroupWise Administration Console so that you can easily refer to it later. Be sure to update the information in the GroupWise objects if the configuration of your system changes.

Recording Cluster-Specific Information about the GWIA Domain and Its MTA

To permanently record important cluster-specific information for the GWIA domain:

  1. Browse to and click the Domain object in the Administration Console.

  2. Navigate to Objects tab > Internet Agents, and click the GWIA object.

  3. In the Description field of the GWIA General tab, provide a cluster-specific description of the GWIA domain, including the secondary IP address of its GroupWise partition.

  4. Click Save to save the GWIA domain description.

  5. Browse to and click the MTA object.

  6. In the Description field of the MTA General tab, record the secondary IP address of the GroupWise partition.

    This information appears on the MTA console, no matter which node in the cluster it is currently running on.

  7. Click Save to save the MTA description.

Knowing What to Expect in an GWIA Failover Situation

The failover behavior of the MTA for the GWIA domain is the same as for an MTA in a regular domain. See Knowing What to Expect in MTA, POA, and DVA Failover Situations.

Failover of the GWIA itself is more complex. The various clients (POP3, IMAP4, and LDAP) receive an error message that the node is not available. Most of the clients do not attempt to reconnect automatically, so the user must exit the client and restart it to reestablish the connection after the failover process is complete. Fortunately, the GWIA restarts quickly in its failover location so users can reconnect quickly.

As with the MTA, the POA, and the DVA, migration of the GWIA takes longer than failover. In fact, the GWIA can seem especially slow to shut down properly as it finishes its normal processing and stops its threads. For a busy GWIA, you might need to wait several minutes for it to shut down properly.

1.6.5 Internet Agent Clustering Worksheet

Item

Explanation

1) GroupWise Partition for the GWIA:

Secondary IP Address:

Specify the GroupWise partition where the GWIA domain will be created, along with its secondary IP address.

For more information, see Selecting the GWIA Partition and Secondary IP Address.

2) GWIA Domain Name:

Domain Database Location:

Specify a unique name for the GWIA domain. Specify the directory on the GroupWise partition where you want to create the new domain.

For more information, see Planning a Domain for the GWIA.

3) GWIA Failover List:

List other nodes in the cluster where the GWIA and its MTA can fail-over.

For more information, see Determining an Appropriate Failover List for the Linux GWIA.

4) Cluster Resource Mount Point:

Specify the mount point directory where the GWIA domain will be mounted.

For more information, see Cluster Resource Information for the Linux GWIA.

1.6.6 Internet Agent Quick Checklist