3.4 Installing and Configuring the Agents in a Linux Cluster

By following the instructions in Section 3.1, Setting Up a New GroupWise System in a Linux Cluster, you created the initial domain and post office in your GroupWise system. You are now ready to install and configure the MTA, POA, and DVA, and set up the agent software for use in your cluster.

IMPORTANT:If you have added a new secondary domain or a new post office to an existing GroupWise partition, 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. In these circumstances, follow the instructions in Section 3.4.4, Setting Up New Instances of the Linux Agents without Installing the Agent Software instead of completing the first three tasks above.

3.4.1 Installing and Setting Up the Linux Agents in Your Cluster

The agents must be installed on each node in domain failover list (Agent Clustering Worksheet item 2) and the post office failover list (Agent Clustering Worksheet item 5).

After you have installed and tested the agents on each node in the cluster, continue with Section 3.4.2, Changing Linux Agent Paths to Locations on GroupWise Partitions.

Running the Linux GroupWise Installation Program on the Preferred Node

  1. Mount the GroupWise partition for the domain (System Clustering Worksheet item 7) or the post office (System Clustering Worksheet item 8).

  2. From the software distribution directory you created in Step 6 in Section 3.1, Setting Up a New GroupWise System in a Linux Cluster, start the Linux GroupWise Installation program.

    IMPORTANT:This time, you should select the Configure GroupWise for Clustering option.

    Configure GroupWise for Clustering option
  3. Install the agent software, following the steps provided in Installing the Linux GroupWise Agents in Installing GroupWise Agents in the GroupWise 2012 Installation Guide.

  4. Configure the Linux agents according to the Agent Clustering Worksheet that you filled out in Section 2.6, Deciding How to Install and Configure the Linux Agents in a Cluster, paying special attention to the cluster resource information on the Domains / Post Offices page.

    Domains / Post Offices page

    As a result of selecting Configure GroupWise for Clustering on the preferred node, the following cluster-specific configuration actions are performed for the MTA and the POA:

    • The agent startup files are created in mount_point/groupwise/agents/share on the shared resource so that the agents use the same startup files regardless of which cluster node the agents are running on. The --home startup switch includes the mount point and the path to the database so that the startup file is valid when mounted to each cluster node.

    • The --cluster startup switch is added to the agent startup files to inform the agents that they are running in a cluster.

    • The --ip startup switch is set to the secondary IP address of the shared resource where the domain and post office are located. This ensures that the MTA and the POA run with the same IP address regardless of which cluster node the agents are running on.

    • The --log startup switch is set to a location on the shared resource (mount_point/groupwise/agents/log) so that agent logging information is written to the same log file regardless of which cluster node the agents are running on.

    • The GroupWise High Availability service is automatically configured on the current cluster node and its configuration file (gwha.conf) is created in the /etc/opt/novell/groupwise directory.

    • A clusterimport.conf file is created in the gwinst subdirectory of the software distribution directory from which you ran the Linux GroupWise Installation program, so that the cluster-specific information collected when you configured the agents on the preferred node is available when you install the agents on subsequent nodes.

    • The agents are not configured to start automatically on system startup. In a cluster, you do not want the agents to start automatically whenever a node restarts.

  5. (Conditional) If you enable the DVA for clustering, configure it according to the Agent Clustering Worksheet, paying special attention to the cluster resource information:

    As a result of selecting Enable the Document Viewer Agent for Clustering on the preferred node, the following cluster-specific configuration actions are performed for the DVA:

    • The DVA startup file is created in mount_point/groupwise/agents/share on the shared resource so that the DVA uses the same startup file regardless of which cluster node it is running on. The DVA --home startup switch includes the mount point so that the startup file is valid when mounted to each cluster node.

    • The DVA --ip startup switch is set to the secondary IP address of the shared resource. This ensures that the DVA runs with the same IP address regardless of which cluster node it is running on.

    • The DVA --log startup switch is set to a location on the shared resource (mount_point/groupwise/agents/log) so that DVA logging information is written to the same log file regardless of which cluster node it is running on.

    • The GroupWise High Availability service configuration file (gwha.conf) is updated with the configuration information for the DVA.

  6. Configure the agents to run as a non-root user, as described in the applicable section of the GroupWise 2012 Installation Guide:

  7. Continue with Running the Linux GroupWise Installation Program on Subsequent Nodes.

Running the Linux GroupWise Installation Program on Subsequent Nodes

  1. On the next node in the GroupWise agent failover list, mount the GroupWise partition for the domain (System Clustering Worksheet item 7) or the post office (System Clustering Worksheet item 8).

  2. From the software distribution directory you created in Step 6 in Section 3.1, Setting Up a New GroupWise System in a Linux Cluster, start the Linux GroupWise Installation program.

    IMPORTANT:You should select the Configure GroupWise for Clustering option again.

    Because of the existence of the clusterimport.conf file in the gwinst subdirectory of the software distribution directory, a new installation option, Import Clustering Data, is now available on the main GroupWise Installation program page.

    GroupWise Installation program main page
  3. Install the agent software on the cluster node as usual, but do not use the Configure option.

  4. On the main page of the Installation program, click Import Clustering Data, then click Next.

    Import Clustering Data page

    All GroupWise agents that you have installed from the software distribution directory are listed, based on the information stored in the clusterimport.conf file.

  5. Select the GroupWise agents that you want to configure on the current cluster node, then click OK.

    The Import Clustering Data option performs the following configuration actions for each subsequent node where you run it:

    • The grpwise script is created in the /etc/init.d directory on the current cluster node. It is configured specifically for the agents you just selected.

    • The GroupWise High Availability service is automatically configured on the current cluster node and its configuration file (gwha.conf) is created in the /etc/opt/novell/groupwise directory. It is configured specifically for the agents you just selected.

    Because the agent startup files and log files are stored on the shared resource, they do not need to be customized for each cluster node.

  6. Configure the agents to run as a non-root user, as described in the applicable section of the GroupWise 2012 Installation Guide:

  7. Repeat Step 1 through Step 6 for each cluster node in the GroupWise agent failover list.

    After you install and configure the agents on each node in each agent’s failover list, the cluster node is ready for the GroupWise agent to fail over to it.

  8. Continue with Testing Your Linux Agent Installation on Each Node.

Testing Your Linux Agent Installation on Each Node

  1. Test the MTA and the POA by starting them with a user interface, as described in Starting the Linux Agents with a User Interface in Installing GroupWise Agents in the GroupWise 2012 Administration Guide.

    /opt/novell/groupwise/agents/bin/gwmta --show @domain.mta &
    /opt/novell/groupwise/agents/bin/gwpoa --show @post_office.poa &
    
  2. Stop the agents by clicking File > Exit.

  3. (Conditional) If you installed the DVA, test it by starting and stopping it:

    rcgrpwise start gwdva
    rcgrpwise stop gwdva
    
  4. After you can see that the agents start successfully, test them by starting them as daemons, as described in Starting the Linux Agents as Daemons in Installing GroupWise Agents in the GroupWise 2012 Administration Guide.

    rcgrpwise start
    rcgrpwise status
    
  5. Stop the agents.

    rcgrpwise stop
    rcgrpwise status
    
  6. Return to Running the Linux GroupWise Installation Program on the Preferred Node for each node in the domain or post office failover list.

When you have installed the agents on all of the nodes in the domain and post office failover lists, continue with Changing Linux Agent Paths to Locations on GroupWise Partitions.

3.4.2 Changing Linux Agent Paths to Locations on GroupWise Partitions

The default locations for some agent files are on the cluster nodes along with the agent 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 ConsoleOne.

Setting the Linux MTA Message Log File Path

If you plan to enable message logging, as described in Enabling MTA Message Logging in Message Transfer Agent in the GroupWise 2012 Administration Guide:

  1. On the GroupWise partition where the domain is located, create the directory where you want to store MTA message log files.

  2. In ConsoleOne, browse to and select the Domain object.

  3. Right-click the MTA object, then click Properties.

  4. Click GroupWise > Message Log Settings.

  5. In the Message Log File Path field, browse to and select the directory you created in Step 1, then click OK.

Setting the Linux MTA Certificate and Key File Path

If you plan to enable SSL, as described in Securing the Domain with SSL Connections to the MTA in Message Transfer Agent in the GroupWise 2012 Administration Guide:

  1. On the GroupWise partition where the domain is located, 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 Server Certificates and SSL Encryption in Security Administration in the GroupWise 2012 Administration Guide.

  3. In ConsoleOne, browse to and select the Domain object.

  4. Right-click the MTA object, then click Properties.

  5. Click GroupWise > SSL Settings.

  6. In the Certificate File field, browse to and select the certificate file.

  7. In the SSL Key File field, browse to and select the key file.

  8. Click OK.

Setting the Linux POA Certificate and Key File Path

If you plan to enable SSL, as described in Securing the Post Office with SSL Connections to the POA in Post Office Agent in the GroupWise 2012 Administration Guide:

  1. On the GroupWise partition where the post office is located, 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 Server Certificates and SSL Encryption in Security Administration in the GroupWise 2012 Administration Guide.

  3. In ConsoleOne, browse to and select the Post Office object.

  4. Right-click the POA object, then click Properties.

  5. Click GroupWise > SSL Settings.

  6. In the Certificate File field, browse to and select the certificate file.

  7. In the SSL Key File field, browse to and select the key file.

  8. Click OK.

3.4.3 Configuring GroupWise Cluster Resources to Load and Unload the Linux Agents

The properties of the Cluster Resource object associated with the GroupWise partition define how partitions function within the cluster, how agents are loaded and unloaded, and how failover and failback situations are handled. At this point, you might have one cluster resource for a GroupWise partition with a domain and post office on it, or you might have two cluster resources for two GroupWise partitions, one for the domain and one for the post office. Complete the following tasks for each cluster resource:

Modifying the Cluster Resource Load Script for the Linux Agents

The cluster resource load script executes whenever the GroupWise partition comes online. On OES Linux, all cluster management activities are performed in Novell iManager.

To set up the load script in iManager:

  1. Expand Clusters, then click Cluster Options.

    Cluster Options page
  2. In the Cluster field, browse to the Cluster object where the GroupWise cluster resource is located.

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

    Cluster Objects list
  4. Select the GroupWise Cluster Resource object that you created when you set up the GroupWise partition, then click Details.

  5. Click Scripts > Load Script.

  6. (Conditional) If this is an NSS volume or a shared pool, use a load script similar to the following example, depending on the configuration of your cluster and nodes:

    #!/bin/bash 
    . /opt/novell/ncs/lib/ncsfuncs
    
    # mount filesystem
    exit_on_error ncpcon mount /opt="noatime,nodiratime" volume_name=volume_ID
    
    # add IP address
    exit_on_error add_secondary_ipaddress gw_partition_ip_address
    
    # start service
    exit_on_error /etc/init.d/grpwise start domain
    exit_on_error /etc/init.d/grpwise start post_office.domain
    exit_on_error /etc/init.d/grpwise start gwdva
    
    1. In the mount filesystem section, specify the volume name and volume ID of the GroupWise partition that you are clustering (System Clustering Worksheet item 5).

    2. In the add IP address section, specify the secondary IP address of the GroupWise partition (System Clustering Worksheet item 7 or System Clustering Worksheet item 8).

    3. In the start service section, use the commands to start the specific GroupWise agents that you want to run on this GroupWise partition.

      If you created a domain on the partition, you need to start the MTA. If you created a post office on the partition, you need to start the POA. If you created both a domain and a post office, you need to start both the MTA and the POA. If you installed the DVA, you need to start it as well.

  7. (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:

    #! /bin/bash
    . /opt/novell/ncs/lib/ncsfunc
    
    # define IP address
    RESOURCE_IP=gw_partition_ip_address
    
    # define filesystem type
    MOUNT_FS=filesystem
    
    # define device (if using EVMS)
    exit_on_error evms -f /var/opt/novell/ncs/ContainerActivate -rl
                                                     Share ‘uname -n‘
    MOUNT_DEV=/dev/evms/Share/dat
    
    # define mount point
    MOUNT_POINT=/mnt/mount_point_directory
    
    # mount filesystem
    exit_on_error mount -t $MOUNT_FS $MOUNT_DEV $MOUNT_POINT -o noatime,nodiratime
    
    # add IP address
    exit_on_error add_secondary_ipaddress $RESOURCE_IP
    
    # start service
    exit_on_error /etc/init.d/grpwise start domain
    exit_on_error /etc/init.d/grpwise start post_office.domain
    exit_on_error /etc/init.d/grpwise start gwdva
    
    exit 0
    
    1. In the define IP address section, specify the secondary IP address of the GroupWise partition (System Clustering Worksheet item 7 or System Clustering Worksheet item 8)

    2. In the define filesystem type section, specify the filesystem type that is 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, use the commands to start the specific GroupWise agents that you want to run on this GroupWise partition.

      If you created a domain on the partition, you need to start the MTA. If you created a post office on the partition, you need to start the POA. If you created both a domain and a post office, you need to start both the MTA and the POA. If you installed the DVA, you need to start it as well.

  8. Click OK to save the load script.

Modifying the Cluster Resource Unload Script for the Linux Agents

The cluster resource unload script executes whenever the GroupWise partition 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 GroupWise cluster resource, click Scripts > Unload Script.

  2. (Conditional) If this is an NSS volume or a shared pool, use an unload script similar to the following example, depending on the configuration of your cluster and nodes:

    #!/bin/bash
    . /opt/novell/ncs/lib/ncsfuncs
    
    # request service stop
    ignore_error /etc/init.d/grpwise stop domain
    ignore_error /etc/init.d/grpwise stop post_office.domain
    ignore_error /etc/init.d/grpwise stop gwdva
    
    # stop service otherwise
    sleep 8
    ignore_error pkill -fx "'/opt/novell/groupwise/agents/bin/gwmta
              @/media/nss/volume_name/groupwise/agents/share/domain_name.mta'"
    ignore_error pkill -fx "'/opt/novell/groupwise/agents/bin/gwpoa
              @/media/nss/volume_name/groupwise/agents/share/
                                                        post_office_name.poa'"
    ignore_error pkill -fx "'/opt/novell/groupwise/agents/bin/gwdva
              @/media/nss/volume_name/groupwise/agents/share/gwdva.dva'"
    
    # delete IP address
    ignore_error del_secondary_ipaddress gw_partition_ip_address
    
    # unmount filesystem
    exit_on_error umount /mnt/mount_point_directory
    
    # return status
    exit 0
    
    1. In the request service stop section, use the commands to stop the specific GroupWise agents that are running on this GroupWise partition.

    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 that follows.

    3. In the delete IP address section, specify the secondary IP address of the GroupWise partition.

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

    5. (Conditional) If you are running the GroupWise High Availability service (gwha), stop it before the script stops the agents, 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. (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:

    #!/bin/bash
    . /opt/novell/ncs/lib/ncsfuncs
    
    # request service stop
    ignore_error /etc/init.d/grpwise stop domain
    ignore_error /etc/init.d/grpwise stop post_office.domain
    ignore_error /etc/init.d/grpwise stop gwdva
    
    # stop service otherwise
    sleep 8
    ignore_error pkill -fx "'/opt/novell/groupwise/agents/bin/gwmta
              @/media/nss/volume_name/groupwise/agents/share/domain_name.mta'"
    ignore_error pkill -fx "'/opt/novell/groupwise/agents/bin/gwpoa
              @/media/nss/volume_name/groupwise/agents/share/
                                                        post_office_name.poa'"
    
    # define IP address
    RESOURCE_IP=gw_partition_ip_address
    
    # define mount point
    MOUNT_POINT=/mnt/mount_point_directory
    
    # delete IP address
    ignore_error del_secondary_ipaddress $RESOURCE_IP
    
    # unmount filesystem
    exit_on_error umount $MOUNT_POINT
    
    # return status
    exit 0
    
    1. In the request service stop section, use the commands to stop the specific GroupWise agents that are running on this GroupWise partition.

    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 that follows.

    3. In the define IP address section, specify the secondary IP address of the GroupWise 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 service (gwha), stop it before the script stops the agents, 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`
      
  4. Click OK to save the unload script.

Setting the Failover List and Policies for the Linux Agents

  1. On the iManager Cluster Resource Properties page of the GroupWise cluster resource, click General.

    Cluster Resource Properties page

    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 Novell Cluster Services Administration Guide for Linux for your version of OES Linux.

  2. Click Preferred Nodes, then arrange the nodes in the cluster into the desired failover list for the domain or post office (under Agent Clustering Worksheet items 3 or 6).

  3. Click OK.

3.4.4 Setting Up New Instances of the Linux 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. When you select the Configure GroupWise for Clustering option, the Linux GroupWise Installation program creates agent startup files in mount_point/groupwise/agents/share on the shared resource.

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 new startup file to find other active (not commented out) startup switches, then modify them as needed for the new agent.

  4. Save the new startup file.

  5. Edit the GroupWise High Availability service configuration file (/etc/opt/novell/groupwise/gwha.conf).

  6. Make a copy of the section for an existing domain and its MTA or post office and its POA, then modify the information for the new domain or post office and its accompanying agent.

  7. Save the gwha.conf file.

    For more information about the High Availability service, see Enabling the GroupWise High Availability Service for the Linux GroupWise Agents in Installation in the GroupWise 2012 Installation Guide.

  8. 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 cluster resource load scripts.

If you created the new domain and/or post office on a new GroupWise partition, skip back to Section 3.4.3, Configuring GroupWise Cluster Resources to Load and Unload the Linux Agents for instructions to create new load and unload scripts.

If you created the new domain and/or post office on an existing GroupWise partition, most of the configuration of the cluster resource is already done. You just need to add new service start and stop commands to the existing scripts. Continue with the steps below:

To modify existing load and unload scripts:

  1. In iManager, expand Cluster, then click Cluster Options.

  2. In the Cluster field, browse to and click the Cluster object where the GroupWise cluster resource is located.

  3. Select a cluster resource that contains a GroupWise partition, then click Properties > Scripts.

  4. Following the pattern of the existing service start commands, add start 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.

  5. Click Apply to save the modified load script.

  6. Click Unload Script.

  7. Add corresponding service stop commands for the new instances of the agents.

  8. Click Apply to save the modified unload script.

    You might want to review other properties of the Cluster Resource object, such as the failover list and the failover/failback/migration procedures on the General page, because an additional domain and/or post office now resides on the GroupWise partition.

  9. Change other Cluster Resource properties as needed.

  10. Click OK to save the modified properties.

  11. In the Cluster Manager, take the GroupWise partition 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 Testing Your Clustered GroupWise System on Linux.