8.4 Setting Up the GroupWise Agents

After creating a new domain or post office, you need to configure the Agent object (MTA or POA) that was automatically created with it, then follow the setup instructions for the platform where you are installing the GroupWise agents:

8.4.1 Configuring New Agent Objects in eDirectory

When you create new post offices and domains, Agent objects are automatically created for them. Most agent configuration can be done after installation, but a few settings should be established before you install the agent software.

  1. In ConsoleOne, browse to and expand the eDirectory container where the new post office or domain is located to display its contents.

  2. Select the Post Office object or Domain object to display its contents.

  3. Right-click the Agent object, then click Properties to display the agent Identification page.

  4. In the Description field, type a brief description of the agent for display at the agent server console.

  5. In the Platform field, select Linux or Windows.

  6. Click OK to save the new Agent object properties.

  7. Repeat these steps for each new post office and domain for which you are installing agents.

  8. Continue with the installation instructions for the platform where you are installing the GroupWise agents.

8.4.2 Linux: Setting Up the GroupWise Agents

IMPORTANT:If you plan to install the GroupWise agents in a clustered server environment, see the GroupWise 2012 Interoperability Guide before you install the agents.

Refer to the following additional tasks as you maintain all the GroupWise agents on Linux:

If you are new to Linux, you might want to review Linux Commands, Directories, and Files for GroupWise Administration in the GroupWise 2012 Administration Guide before you install the GroupWise agents on Linux.

Preparing the Linux Server for the GroupWise Agents

  1. Ensure that the Linux server where you are installing the GroupWise agents meets the system requirements listed in Section 8.2, Agent System Requirements.

  2. Ensure that the Linux operating system media is available, in case the GroupWise Installation program needs to install supporting packages on the Linux server.

  3. Ensure that the Linux server has a static IP address.

  4. Ensure that the firewall on the Linux server has the ports open that are used by the MTA, the POA, and the DVA.

    For assistance, see GroupWise Port Numbers in the GroupWise 2012 Administration Guide.

  5. Continue with Installing the Linux GroupWise Agents.

Installing the Linux GroupWise Agents

Running the GUI GroupWise Installation Program
  1. In a terminal window on the server where you want to install the GroupWise agents, log in as root, then provide the root password.

  2. Change to the root directory of the downloaded GroupWise 2012 software image.

    or

    If you have already copied the agent software to a software distribution directory, change to /opt/novell/groupwise/software.

  3. Run ./install.

    The X Window System is required for running the GUI GroupWise Installation program. If you are not using the X Window System, you can install GroupWise components individually, as described in Installing GroupWise Components Using the Text-Based Installation Program.

  4. Select the language in which you want to run the GroupWise Installation program, then click OK.

    The main GroupWise System Installation page appears.

    GroupWise Installation program
  5. Click Install Products > GroupWise Agents > Install Agents to install the GroupWise agent software.

  6. When the installation is complete, click OK.

    The GroupWise agent software is installed to the following directory:

    /opt/novell/groupwise/agents
    
  7. Click Configure GroupWise Agents.

    Linux Agent Configuration program
  8. Follow the prompts to provide Linux Agent information from your GroupWise Agent Installation Worksheet.

    On the Configuration Complete page, Launch GroupWise Agents on System Startup is selected by default.

    IMPORTANT:If you want to configure the agents for high availability, as described in Enabling the GroupWise High Availability Service for the Linux GroupWise Agents, they must be configured to start automatically on system startup.

  9. (Conditional) If you do not want the agents to start automatically when the server restarts, deselect Launch GroupWise Agents on System Startup.

  10. Click Exit to exit the GroupWise Agent Installation program.

  11. Exit the GroupWise Installation program.

  12. Skip to Starting the Linux GroupWise Agents.

Installing GroupWise Components Using the Text-Based Installation Program

If you want to install any of the GroupWise agents or applications on a server where the X Window System is not running, you can use the text-based GroupWise Installation program. The server must have openmotif-libs installed. You must still use ConsoleOne to create the associated domain or post office before you can install and configure the agent or application software.

  1. Run install from the root of the downloaded GroupWise 2012 software image.

    or

    If you have already copied the software to a software distribution directory, run ./install from the root of the software distribution directory to start the GroupWise Installation program.

    If you need to perform the installation from a remote location, you can use ssh to access the remote Linux server. Copy the linux subdirectory of the downloaded GroupWise 2012 software image to the server where you want to install the agent software, then run the text-based GroupWise Installation program to install the agents or applications on the Linux server.

  2. Enter the number of the language you want to use for the installation.

  3. Enter y if you want to configure the GroupWise components for clustering.

    or

    Enter n if you are not installing the GroupWise components in a cluster.

  4. Enter the number of the language you want to use for reading the License Agreement.

  5. Press any key to scroll through the License Agreement, then enter y to accept the License Agreement.

  6. In the list of components, enter the number for the GroupWise component that you want to install.

    1. GroupWise Agents
    2. GroupWise WebAccess
    3. GroupWise Monitor
    4. GroupWise Internet Agent
    5. GroupWise Calendar Publishing Host
    6. View the Readme
    0.1 Exit
    
  7. In the list of actions, enter 1 to install the agent or application software.

    1. Install GroupWise Agents
    2. Configure GroupWise Agents
    0. Return
    

    A status bar indicates progress.

  8. When the installation is complete, enter y to configure the component.

  9. Follow the prompts to provide the configuration information, then press any key to exit.

    In the text-based Installation program, you can press Ctrl+C to return to the previous menu.

  10. (Optional) To install additional components, start the text-based Installation program again.

NOTE:The text-based GroupWise Installation program does not run on all Windows versions of ssh. An open source product named PuTTY that can be downloaded from the Internet free of charge is compatible with the text-based GroupWise Installation program. There are several Web sites where PuTTY is available for download.

Starting the Linux GroupWise Agents

Starting the Linux Agents with a User Interface
  1. In a terminal window, become root by entering su - and the root password.

  2. Change to the GroupWise agent bin directory.

    cd /opt/novell/groupwise/agents/bin

  3. Enter one of the following commands to start the MTA:

    Syntax:
    ./gwmta --show --home domain_directory &
    ./gwmta --show @domain.mta &
    
    Example:
    ./gwmta --show --home /gwsystem/domlnx &
    ./gwmta --show @provo.mta &
    

    The --show startup switch starts the MTA with a server console interface similar to that provided for the Windows MTA. This user interface requires that the X Window System and Open Motif be running on the Linux server.

    The --home startup switch specifies the domain directory and is required to start the MTA.

    The @domain.mta startup switch specifies the MTA startup file, which contains the --home startup switch. The MTA startup file is named after the domain that the MTA services. The Installation program created the MTA startup file in the /opt/novell/groupwise/agents/share directory. Because the Installation program prompted you for the domain directory, it set the --home switch for you in the startup file.

    The ampersand (&) causes the MTA to run in the background, so that the terminal window you started it in is again available for use.

    To remind yourself of these commands when you are at your Linux server, view the gwmta man page.

    MTA console on Linux

    The status messages displayed on the MTA server console are also written to the MTA log file (mmddmta.nnn) in the /var/log/novell/groupwise/domain.mta directory. The log file name includes the month and day when it was created, along with an incrementing extension to accommodate multiple log files on the same day.

    In ConsoleOne, you can see that the MTA has updated the domain database because the Version field on the Identification page of the Domain object shows 12 when the database update is complete.

  4. Wait until the domain database has been updated before you start the POA.

  5. Use the following command to start the POA:

    Syntax:
    ./gwpoa --show --home post_office_directory &
    ./gwpoa --show @post_office.poa &
    
    Example:
    ./gwpoa --show --home /gwsystem/polnx &
    ./gwpoa --show @research.poa &
    

    The --home startup switch specifies the post office directory and is required to start the POA.

    The @post_office.poa startup switch specifies the POA startup file, which contains the --home startup switch. The POA startup file is named after the post office that the POA services. The Installation program created the POA startup file in the /opt/novell/groupwise/agents/share directory. Because the Installation program prompted you for the post office directory, it set the --home switch for you in the startup file.

    To remind yourself of these commands when you are at your Linux server, view the gwpoa man page.

    POA console on Linux

    The status messages displayed on the POA server console are also written to the POA log file (mmddpoa.nnn) in the /var/log/novell/groupwise/post_office.poa directory. The log file name includes the month and day when it was created, along with an incrementing extension to accommodate multiple log files on the same day. The POA also maintains a symbolic link to a file named poa.currentlog, where poa is the name of the POA eDirectory object. This link points to the current POA log file, regardless of the date and incrementing extension of the actual POA log file name. This facilitates monitoring the current POA log file using the tail command.

    In ConsoleOne, you can see that the POA has updated the post office database because the Version field on the Identification page of the Post Office object shows 12 when the database update is complete.

    If you encounter any problems starting the GroupWise agents, see Strategies for Agent Problems in GroupWise 2012 Troubleshooting 2: Solutions to Common Problems for assistance.

    After the post office database has been updated, users can connect to the post office using the Windows client or GroupWise WebAccess.

    When you start the Linux agents with a user interface, you can use the agent server consoles described in the following sections in the GroupWise 2012 Administration Guide.

Starting the Linux Agents as Daemons

All of the Linux GroupWise agents except the Monitor Agent can be started as daemons by using the grpwise script. By default, the grpwise script starts the agents without a user interface.

The Monitor Agent uses its own customized grpwise-ma script that works essentially the same way.

  1. Make sure you are logged in as root.

  2. Change to the /etc/init.d directory.

  3. To start all of the Linux GroupWise agents that are installed on the server, enter the following command:

    ./grpwise start
    
  4. To confirm that the agents have started, enter the following command:

    ./grpwise status
    

    IMPORTANT:The GroupWise agents are Run Control compliant. During installation, a symbolic link is created from /etc/init.d/grpwise to /usr/sbin/rcgrpwise. Typically, /usr/sbin is already on your path, so you can run rcgrpwise from any directory, rather than changing to /etc/init.d in order to run the grpwise script. A /usr/sbin/grpwise-ma link is also created for the Monitor Agent.

    Agent status is displayed in terms of the names of the domain and post office associated with each agent. It lists the agent locations in the following format:

    POA:

    post_office.domain

    MTA:

    domain

    DVA:

    gwdva

    GWIA:

    gwia.domain

    When using the grpwise script, you refer to the agents by the location names displayed when you list agent status, not by the names of the agent executables.

  5. Use the following set of commands as needed to start the agents as daemons and verify their status:

    ./grpwise start
    rcgrpwise start
    

    Starts the GroupWise agents that are installed on the server

    ./grpwise start agent_location_name
    rcgrpwise start agent_location_name
    

    Starts the specified agent

    ./grpwise status
    rcgrpwise status
    

    Displays the status of the GroupWise agents that are installed on the server

    ./grpwise status agent_location_name
    rcgrpwise status agent_location_name
    

    Displays the status of the specified agent

    ./grpwise print
    rcgrpwise print
    

    Lists the contents of the gwha.conf file

    For convenience in typing the command, the agent_location_name is not case sensitive.

    To remind yourself of these commands when you are at your Linux server, view the grpwise man page.

    If Novell Messenger agents are installed on the same server, the grpwise script also starts them.

  6. (Optional) To cause the grpwise script to start the agents with a user interface, use the show = yes option in the GroupWise High Availability service configuration file (gwha.conf).

    For more information, see Configuring the GroupWise High Availability Service in the gwha.conf File.

Starting the Linux Agents on System Startup

If you selected Launch GroupWise Agents on System Startup in the Installation program, the Installation program configured your system so that the agents start automatically each time you restart your server. The Agent Installation programs always creates a grpwise startup script in /etc/init.d for starting the agents, as described in Starting the Linux Agents as Daemons. To enable automatic startup, the Agent Installation programs also create symbolic links named Snngrpwise in the rc3.d and rc5.d directories so that the agents load on restart into level 3 or 5, depending on the configuration of your Linux system. The value of nn is determined by the chkconfig command during installation so that the GroupWise agents are started in the proper sequence with other processes running on the server.

When the grpwise script runs and starts the GroupWise agents, the agents read the agent startup files in /opt/novell/groupwise/agents/share to check for configuration information provided by startup switches. Because the --show switch cannot be used in the startup files, the agents do not run with server console interfaces when started automatically when the server restarts, unless you modify the gwha.conf file as described in Enabling the GroupWise High Availability Service for the Linux GroupWise Agents.

Restarting the Linux Agents Automatically

You can use the GroupWise High Availability service, in conjunction with GroupWise Monitor, to detect when a GroupWise agent has stopped unexpectedly and to restart it automatically. For setup instructions, see Enabling the GroupWise High Availability Service for the Linux GroupWise Agents.

Stopping the Linux GroupWise Agents

How you stop the Linux GroupWise Agents depends on how you started them.

Stopping the Linux Agents from the Agent Console User Interface

When you use the --show startup switch to start the GroupWise agents, you can stop them from the agent server console interface.

  1. Click File > Exit > Yes.

Stopping the Linux Agents Using the grpwise Script

When you start the GroupWise agents with the grpwise script, you can also use the script to stop them. This also applies for the Monitor Agent and its grpwise-ma script.

  1. Make sure you are logged in as root.

  2. Change to the /etc/init.d directory.

  3. To stop all of the GroupWise agents installed on the server, enter the following command:

    ./grpwise stop
    
  4. To confirm that the agents have stopped, enter the following command:

    ./grpwise status
    

    IMPORTANT:The GroupWise agents are Run Control compliant. During installation, a symbolic link is created from /etc/init.d/grpwise to /usr/sbin/rcgrpwise. Typically, /usr/sbin is already on your path, so you can run rcgrpwise from any directory, rather than changing to /etc/init.d in order to run the grpwise script. A /usr/sbin/grpwise-ma link is also created.

    Agent status is displayed in terms of the names of the domain and post office associated with each agent. It lists the agent locations in the following format:

    POA:

    post_office.domain

    MTA:

    domain

    DVA:

    gwdva

    GWIA:

    gwia.domain

  5. Use the following set of commands as needed to stop the agents as daemons and verify their status:

    ./grpwise stop
    rcgrpwise stop
    

    Stops the GroupWise agents that are installed on the server

    ./grpwise stop agent_location_name
    rcgrpwise stop agent_location_name
    

    Stops the specified agent

    ./grpwise status
    rcgrpwise status
    

    Displays the status of the GroupWise agents that are installed on the server

    ./grpwise status agent_location_name
    rcgrpwise status agent_location_name
    

    Displays the status of the specified agent

    For convenience in typing the command, the agent_location_name is not case sensitive.

Stopping the Linux Agents Manually as Daemons

When you start the GroupWise agents manually on the command line (without using the grpwise script), use the standard Linux kill command to stop them.

  1. Make sure you are logged in as root.

  2. Determine the process IDs (PIDs) of the agent to kill:

    POA:

    ps -eaf | grep gwpoa

    MTA:

    ps -eaf | grep gwmta

    DVA

    ps -eaf | grep gwdva

    GWIA:

    ps -eaf | grep gwia

    Monitor:

    ps -eaf | grep gwmon

    All of the PIDs for the specified agent are listed.

  3. Kill the first process listed for each agent:

    Syntax:
    kill PID
    
    Example:
    kill 1483
    kill 1892
    

    It might take a few seconds for all agent processes to terminate.

  4. Repeat the ps commands to verify that the agents have stopped.

You can also restart the MTA and the GWIA without stopping them first using the following command:

Syntax:
kill -HUP PID
Example:
kill -HUP 1483

The -HUP (hang up) option is equivalent to using Restart in the MTA and GWIA server console or Web console. Because the other agents do not have a Restart feature in their consoles, the -HUP option cannot be used to restart them.

Running the Linux GroupWise Agents as a Non-root User

For security reasons, it is preferable that the GroupWise agents do not run with root user privileges. For example, if an intruder manages to assume the identity of a GroupWise agent, the intruder gains all the privileges of the commandeered process. If the process is running with root user privileges, then the intruder has root access to your system. If the process is running as a user with minimal privileges, then the intruder has only restricted access to your system. Therefore, your system is more secure if the GroupWise agents do not run as root.

The root user still needs to start the agents, because the agents do need to access some root-only resources on startup. However, you can configure the agents to switch to a different user after they start. After the agents are running as the non-root user, they need adequate access to the locations where each domain, post office, library, and software distribution directory is located.

NOTE:You can configure the POA, MTA, and GWIA to run as a non-root user. The DVA must still run as root. Unlike the other agents, the Monitor Agent can be started as a non-root user by default, so no setup is required for it to run as a non-root user.

Setting Up Typical Non-root Access

To configure the GroupWise agents to switch users after startup:

  1. Make sure you are logged in as root.

  2. Select a Linux user for the agents to run as and make sure that the user is listed in the /etc/passwd file.

    You might want to create a new user specifically for this purpose, perhaps named gwagents.

  3. Change to the groupwise directory under /etc:

    cd /etc/opt/novell/groupwise
    
  4. Create a new agents directory, then change to that directory:

    mkdir agents
    cd agents
    
  5. Create a file named uid.conf.

  6. Type the selected user name in the file, for example:

    gwagents
    
  7. Stop and then start the agents.

    While starting as root, the agents automatically change the ownership of the domain and post office directory structures from root to the user you specified in the uid.conf file. Then they switch users and run as the user you specified, rather than as root.

    If you list the agent processes, you can observe that they are no longer running as root.

    ps -eaf | grep gw
    

    If the post office and domain are located on different servers, you must complete the above steps on each server.

    IMPORTANT:All agents running on the same server must run as the same user. The first time you start an agent as a non-root user, or if you change from one non-root user to another, the agent might take longer than usual to start, because of the change in ownership of the directories and files accessed by that agent. This is especially true of a POA that services a large post office and that requires access to a restore area, especially a restore area on a remote server.

If you later want to change the user that the agents are running as, follow the instructions in Changing the Non-root User.

Setting Up Non-root Access on an NSS Volume on Novell Open Enterprise Server Linux

When your domains, post offices, libraries, and software distribution directories are located on a Novell Open Enterprise Server (OES) Linux NSS volume, you must set up an eDirectory user for the agents to run as and you must Linux-enable that user. On OES Linux, you can use Novell iManager to accomplish these tasks.

To configure the agents to switch users after startup and provide access to an NSS volume:

  1. Select or create an eDirectory user for the agents to run as.

    You might want to create a new user specifically for this purpose, perhaps named gwagents. The user name must not match any local user names on the Linux server.

    1. From the Open Enterprise Server Welcome page in your Web browser, expand Network Management, then click iManager 2.5.x.

    2. In the iManager Links box, click Open Novell iManager 2.5.

    3. To log in to iManager, specify a user name, a password, and a tree.

    4. In the left pane, expand Users, then click Create User.

    5. Provide the required information, then click OK.

      The user does not need a password

  2. Linux-enable the user you just created:

    1. In the left pane, expand Linux User Management, then click Enable User for Linux.

    2. Browse to and select the user you just created, then click OK.

    3. Select the primary group for the user to belong to (for example, admingroup).

    4. Change /bin/bash to /bin/false because the user does not need a shell.

    5. Click OK to Linux-enable the user.

  3. In a terminal window, change to the groupwise directory under /etc:

    cd /etc/opt/novell/groupwise
    
  4. Create a new agents directory, then change to that directory.

    mkdir agents
    cd agents
    
  5. Create a file named uid.conf

  6. Type the selected user name in the file, for example:

    gwagents

  7. Use the following command to grant the user the required rights to the directories that the agents need to access on the local server:

    rights -f /directory -r rwcemf trustee user.context.tree
    

    The POA needs access to the post office directory. The MTA and the GWIA need access to the domain directory.

  8. Stop and then start the agents.

    While starting as root, the agents automatically change the ownership of the domain and post office directory structures from root to the user you specified in the uid.conf file. Then they switch users and run as the user you specified, rather than as root.

    If you list the agent processes, you can observe that they are no longer running as root.

    ps -eaf | grep gw
    

    If the post office and domain are located on different servers, you must complete the above steps on each server.

    IMPORTANT:All agents running on the same server must run as the same user.

If you later want to change the user that the agents are running as, follow the instructions in Changing the Non-root User.

Changing the Non-root User

To prevent an agent from running as a different user than the one for which it was originally configured, the GroupWise agents create a uid.run file in the domain or post office directory that they service. The GWIA creates the uid.run file in its gateway directory (typically domain/wpgate/gwia).

If, for any reason, the user specified in the uid.run file does not match the user specified in the uid.conf file, the agent displays the following message:

Error: Running the agent with conflicting effective users

This could happen if the user specified in the uid.conf file is manually edited, or if the uid.conf file is deleted, thus changing or removing the information about the user that the agent should run as. If this message appears, verify that the uid.conf file specifies the desired user, then delete the uid.run file.

After displaying the message, the agent does not start, because it no longer has appropriate permissions in the domain or post office directory that it needs to service. By deleting the uid.run file, you enable the agent to reset the permissions in the domain or post office directory to appropriate user and then start successfully.

After configuring an agent to run as a specific non-root user:

  • If you want the agent to run as a different non-root user, modify the uid.conf file in the /etc/opt/novell/groupwise/agents directory to specify the desired non-root user, then delete the uid.run file from the directory serviced by the agent.

  • If you want the agent to run as root, delete the uid.conf file from the /etc/opt/novell/groupwise/agents directory and delete the uid.run file from the directory serviced by the agent.

Enabling the GroupWise High Availability Service for the Linux GroupWise Agents

The GroupWise High Availability service (gwha) makes sure that if the MTA, POA, DVA, or GWIA goes down for any reason, it restarts automatically. On Windows, Microsoft Clustering Services automatically restarts a service that is not responding. However, on Linux, some clustering environments do not include this capability, so it is built into the Linux GroupWise agents.

The GroupWise High Availability service is installed automatically, starts when your server boots, and makes sure that any GroupWise agents installed on the server restart if they go down unexpectedly. However, the GroupWise High Availability service does not start the GroupWise agents initially. For more information, see Starting the Linux Agents on System Startup.

The GroupWise High Availability service relies on the Monitor Agent to detect when a GroupWise agent is no longer running. The Monitor Agent notifies the GroupWise High Availability service of any problem, then the GroupWise High Availability service immediately issues the command to start the problem agent. The GroupWise High Availability service runs as root, as configured in the /etc/xinetd.d/gwha file.

A single Monitor Agent can service multiple instances of the GroupWise High Availability service on multiple servers, as long as all instances use the same user name and password to communicate with the Monitor Agent.

Configuring the GroupWise High Availability Service in the gwha file

The basic configuration for the GroupWise High Availability service is contained in the /etc/xinetd.d/gwha file:

socket_type = stream
user = root
server = /opt/novell/groupwise/agents/bin/gwha
wait = no
instances = 1
protocol = tcp
type = UNLISTED
port = 8400
disable = yes

The only option you can change in this file is the port number. By default, the GroupWise High Availability service listens on port 8400. If that port number is already in use on the server where you are setting up the GroupWise High Availability service, you can change the port number in the gwha file. The GroupWise High Availability service must use the same port number on all servers where you want it to restart the GroupWise agents.

Do not change any other options in this file.

Configuring the GroupWise High Availability Service in the gwha.conf File

The interaction between the GroupWise High Availability service and the GroupWise agents is controlled by gwha.conf file located in the /etc/opt/novell/groupwise directory. The configuration file provides a section for configuring SSL for communication between the GroupWise High Availability service and the Monitor Agent. The [gwha] section is followed by sections for each agent installed on the server, as shown below. The headings for the sections match the agent locations listed in Starting the Linux Agents as Daemons.


[gwha]
ssl       = no
key       =
cert      =
password  =

[domain_name]
server    = /opt/novell/groupwise/agents/bin/gwmta
command   = /etc/init.d/grpwise
startup   = domain_name.mta
delay     = 2
wait      = 10

[post_office_name.domain_name]
server    = /opt/novell/groupwise/agents/bin/gwpoa
command   = /etc/init.d/grpwise
startup   = post_office_name.poa
delay     = 2
wait      = 10

[gwia.domain_name]
server    = /opt/novell/groupwise/agents/bin/gwia
command   = /etc/init.d/grpwise
startup   = gwia.cfg
delay     = 2
wait      = 10

[gwdva]
server    = /opt/novell/groupwise/agents/bin/gwdva
command   = /etc/init.d/grpwise
startup   = gwdva.dva
delay     = 2
wait      = 10

To set up the GroupWise High Availability service:

  1. In a terminal window, become root by entering su - and the root password.

  2. Before starting to configure the GroupWise High Availability service, test the agents by starting and stopping them manually with a user interface so that their agent server consoles display:

    1. Change to the root directory of the Linux server.

    2. Start the GroupWise agents manually, including providing the full path to the executable and including the --show switch, to make sure that they are set up and configured correctly.

      /opt/novell/groupwise/agents/bin/gwpoa --show @post.poa
      /opt/novell/groupwise/agents/bin/gwmta --show @dom.mta
      /opt/novell/groupwise/agents/bin/gwia --show @gwia.cfg
      
    3. After verifying that the agents start correctly, stop the agents.

  3. (Conditional) If you use SSL, you need to modify the GroupWise High Availability service configuration file (gwha.conf):

    1. Change to the /etc/opt/novell/groupwise directory.

    2. Edit the gwha.conf file in a text editor.

    3. Under the [gwha] section, fill in the fields as follows:

      [gwha]
      ssl      = yes
      key      = file_name.key
      cert     = file_name.crt
      password = password
      
    4. Save the file, then exit the text editor.

  4. (Conditional) If you changed the port number for the GroupWise High Availability service, as described in Configuring the GroupWise High Availability Service in the gwha file, add the following line to the [gwha] section:

    port = port_number
    

    Replace port_number with the new port number you specified in the gwha file.

  5. (Conditional) If you want to control how the script manages starting and stopping the agents, modify the delay = and wait = settings.

    The delay = setting controls the length of time between when the script issues the command to start an agent and when the script displays a message indicating that the agent has started. The default delay time is 2 seconds. Under certain circumstances, an agent could encounter a problem and fail to start after 2 seconds. In this case, you would receive the success message but the agent would not be running. You need to increase the delay = setting to accommodate the length of time it typically takes for the agent to start successfully on your system.

    The wait = setting controls the length of time between when the script issues the command to stop an agent and when the script kills the agent if the agent has not yet stopped. The default wait time is 10 seconds. Under certain circumstances, an agent could take longer than 10 seconds to perform a normal shutdown, and killing the agent under those circumstances would not be appropriate. You need to increase the wait = setting to accommodate the length of time it usually takes for the agent to shut down. A message notifies you if the script kills an agent because its shutdown exceeds the wait = setting.

    The default settings are usually appropriate, so you do not need to change them unless you frequently encounter problems with starting or stopping an agent with the script.

    1. Change to the /etc/opt/novell/groupwise directory.

    2. Edit the gwha.conf file in a text editor

      Each agent has its own section in the file, for example:

      [Provo2]
      server = /opt/novell/groupwise/agents/bin/gwmta
      command = /etc/init.d/grpwise
      startup = Provo2.mta
      delay = 2
      wait = 10
      
    3. Change the delay = and wait = settings as needed.

    4. Save the file, then exit the text editor.

  6. (Conditional) If you want the script to start the agents with a user interface on the Linux server, add the show = setting in the GroupWise High Availability service configuration file (gwha.conf). This is equivalent to using the --show startup switch on the command line when starting the agent.

    1. Change to the /etc/opt/novell/groupwise directory.

    2. Edit the gwha.conf file in a text editor

      Each agent has its own section in the file, for example:

      [Provo2]
      server = /opt/novell/groupwise/agents/bin/gwmta
      command = /etc/init.d/grpwise
      startup = Provo2.mta
      delay = 2
      wait = 10
      
    3. Add show = yes to the section for each agent that you want to start with a user interface.

      If you need to eliminate the user interface, use show = no or delete the show = line from the file.

    4. Save the file, then exit the text editor.

  7. Enable the GroupWise High Availability service:

    1. In YaST, click Network Services > Network Services (inetd).

    2. (Conditional) If necessary, select Enable to activate the list of services.

    3. Scroll down to the gwha line, select it, then click Toggle Status (On or Off) to change the status to On.

    4. Click Finish.

  8. Start the agents:

    rcgrpwise start
    
  9. Verify agent status:

    rcgrpwise status
    

    For more information about using the grpwise script, see Starting the Linux Agents as Daemons

  10. Repeat this procedures on all servers where you want the GroupWise High Availability service to restart the GroupWise agents.

  11. Continue with Creating a GroupWise High Availability Service User.

Creating a GroupWise High Availability Service User

The GroupWise High Availability service needs a login user on each server where GroupWise agents need to be restarted.

  1. Create a new user and associated password on the local Linux server to represent the GroupWise High Availability service.

    You might name it gwha.

    IMPORTANT:Use a local user account for use only by the GroupWise High Availability service. Do not use a Novell Linux-enabled user. Do not use root.

  2. Create the same user on each Linux server where you want the GroupWise High Availability service to restart the GroupWise agents.

  3. Continue with Configuring the Monitor Agent to Communicate with the GroupWise High Availability Service.

Configuring the Monitor Agent to Communicate with the GroupWise High Availability Service

After you have the GroupWise High Availability service set up and working correctly on all Linux servers where you want it to restart the GroupWise agents, you need to configure the Linux Monitor Agent to communicate with it and test it to make sure that you can rely on it in the future. Although you need a GroupWise High Availability service running on each Linux server where there are GroupWise agents, you need only one Monitor Agent to monitor all agents in your GroupWise system.

  1. Configure the Linux Monitor Agent with the --hauser and --hapassword startup switches.

    If you use the grpwise-ma script to start the Monitor Agent, as described in Starting the Linux Monitor Agent as a Daemon, you can edit it to include the switches:

    1. Change to the /etc/init.d directory, then edit the grpwise-ma script.

    2. Locate the following line:

      #MA_OPTIONS="--hauser user_name --hapassword password 
                   --hapoll 120"
      
    3. Remove the pound sign (#) from the beginning of the line.

    4. Replace user name and password with the user name and password you established in Step 1 in Configuring the GroupWise High Availability Service in the gwha.conf File.

      MA_OPTIONS="--hauser gwha --hapassword gwagents --hapoll 120"
      

      The Monitor Agent uses the --hauser and --hapassword switches to communicate with the GroupWise High Availability service on port 8400, as configured in the /etc/xinetd.d/gwha file. When the Monitor Agent notices that a GroupWise agent has stopped, it notifies the GroupWise High Availability service. Then the GroupWise High Availability service issues the command to restart the problem agent.

      The --hapoll switch specifies that the Monitor Agent should check the status of GroupWise agents every 120 seconds.

      You can use the MA_OPTIONS variable to add any other Monitor Agent startup switches to the grpwise-ma script as needed. For information about Monitor Agent startup switches, see Using Monitor Agent Startup Switches in Monitor in the GroupWise 2012 Administration Guide.

    5. Save the script file, then exit the text editor.

  2. Start the Monitor Agent.

    rcgrpwise-ma start
    
  3. Stop one of the agents, as described in Stopping the Linux GroupWise Agents.

  4. Check the status of the agent you stopped to make sure it is stopped.

  5. Wait for the next Monitor Agent polling cycle.

    You can check and, if necessary, change the Monitor Agent polling cycle in the Monitor Agent Web console. Click Preferences, then scroll down to the HTTP Settings section.

  6. After the polling cycle has passed, check the status of the agent again.

    The agent that you stopped should now be running again.

Monitoring the Linux GroupWise Agents from Your Web Browser

To monitor any GroupWise agent from your Web browser, view the agent Web console by supplying the IP address or DNS hostname and the port number of the agent. The following table lists the default port numbers:

POA:

http://server_network_address:7181

MTA:

http://server_network_address:7180

GWIA:

http://server_network_address:9850

DVA:

http://server_network_address:8301

Monitor:

http://server_network_address:8200

Linux POA Web Console

For more information about the agent Web consoles, including instructions on protecting the agent Web consoles with passwords, see the following sections in the GroupWise 2012 Administration Guide.

Uninstalling the Linux GroupWise Agents

If you move the GroupWise agents to a different server, the GroupWise agent software can be uninstalled just like any other software on Linux. To determine what GroupWise software is currently installed on the Linux server, use the following command:

rpm -qa | grep groupwise

This lists all of the GroupWise RPM packages on the server. The POA the MTA, and the DVA are together in the same RPM. WebAccess has its own RPM Monitor has two RPMs each, one for the agent software and one for the application software. The following list shows all GroupWise agent and administration RPMs that you might need to uninstall from a server:

POA, MTA, and DVA:

novell-groupwise-agents-version-date

GWIA:

novell-groupwise-gwia-version-date

WebAccess Application:

novell-groupwise-webaccess-version-date

Monitor Agent:

Monitor Application:

novell-groupwise-gwmon-version-date

novell-groupwise-monitor-version-date

Calendar Publishing Host Application:

novell-groupwise-calhost-version-date

GroupWise High Availability Service:

novell-groupwise-gwha-version-date

GroupWise Administrator snap-ins:

novell-groupwise-admin-version-date

GroupWise Check:

novell-groupwise-gwcheck-version-date

GroupWise Database Copy:

novell-groupwise-dbcopy-version-date

Use the following command to uninstall a GroupWise RPM package:

rpm -e novell-groupwise-package

Uninstalling the RPMs does not uninstall files created after installation by the GroupWise programs. To see what GroupWise files are created in locations other than under /opt/novell/groupwise and its subdirectories, see Agent Installation Directories in the GroupWise 2012 Troubleshooting 3: Message Flow and Directory Structure:

8.4.3 Windows: Setting Up the GroupWise Agents

Complete the following tasks to set up the Windows agents. These tasks are designed to help you get the Windows POA and MTA up and running as quickly as possible:

IMPORTANT:If you plan to install the GroupWise agents in a clustered server environment, see the GroupWise 2012 Interoperability Guide before you install the agents.

Refer to the following additional tasks as you maintain all the GroupWise agents on Windows:

Preparing the Windows Server for the Windows Agents

  1. Make sure that the Windows server where you are installing the GroupWise agents meets the system requirements listed in Section 8.2, Agent System Requirements.

  2. Make sure that the Windows server has a static IP address.

  3. Make sure that the firewall on the Windows server has the ports open that are used by the MTA, the POA, and the DVA.

    For assistance, see GroupWise Port Numbers in the GroupWise 2012 Administration Guide.

  4. Make sure that no other GroupWise agents are currently running on the server where you want to install the agents.

  5. Log in to eDirectory with Admin-equivalent rights to the eDirectory tree where you want the Installation program to create the Agent objects.

  6. (Optional) Enable SNMP.

    If you want to monitor the GroupWise Windows agents from an SNMP manager program, SNMP must be enabled on the Windows server where the agents are installed. If it is not already enabled, you must enable it before you run the Installation program.

    For example, in Windows Server 2008:

    1. In the Server Manager, right-click Features, then click Add Features.

    2. Select SNMP Services, then click Next.

    3. Click Install.

  7. Continue with Installing the Windows Agent Software.

Installing the Windows Agent Software

  1. Change to the root directory of the downloaded GroupWise 2012 software image.

    or

    If you have already copied the agent software to a software distribution directory, change to that location

  2. Run setup.exe.

  3. (Conditional) If prompted, select the interface language for the Installation program, then click OK.

    On Windows, the GroupWise 2012 software image can be downloaded in a multilanguage version or an English-only version. When you install from the multilanguage version, all languages are always installed, regardless of the specific language that you select for running the Installation program.

    The main GroupWise System Installation page appears.

    GroupWise Installation program main page
  4. Click Install GroupWise System, then click Yes to accept the License Agreement and display the Installation Type page.

    Installation Type page

    When you install the agents, you are performing a Standard installation. Other installation options on this page are described in Setting Up Predefined Installations.

  5. Click Next to accept the default of Standard.

    GroupWise Components page
  6. Select Install Individual Components, then deselect GroupWise Administration.

  7. Follow the prompts to provide the Windows agent information from your GroupWise Agent Installation Worksheet.

    Summary and Modification page
  8. On the Summary and Modification page:

    1. Review the installation information you have provided.

    2. (Conditional) If you need to change information, select the information to change, then click Edit Setting, specify the desired information, then click OK.

  9. Click Install to start the agent installation.

    Status messages keep you informed about the installation progress.

    The GroupWise agents are installed to the following directory:

    c:\Program Files\Novell\GroupWise Server\Agents
    
  10. Click Finish to exit the Agent Installation program.

    If you want to start the agents later or if the Installation program fails to start them successfully, see Starting the Windows GroupWise Agents.

  11. To monitor an agent from your Web browser, view the agent Web console as described in the following sections of the GroupWise 2012 Administration Guide:

  12. If you want to learn more about running the Windows agents, continue with Starting the Windows GroupWise Agents and Stopping the Windows GroupWise Agents.

    or

    If you want to customize the configuration of the Windows agents or expand your GroupWise system, skip to Section 8.5, What’s Next.

  13. Continue with Starting the Windows GroupWise Agents.

Starting the Windows GroupWise Agents

You might have one or more GroupWise agents installed on each Windows server in your GroupWise system. You can start the GroupWise agents on Windows in several ways:

If you encounter any problems starting the GroupWise agents, see Strategies for Agent Problems in GroupWise 2012 Troubleshooting 2: Solutions to Common Problems for assistance.

Starting the Windows Agents Manually As Applications

On the Windows desktop, click Start > All Programs, select the GroupWise agent, then start the GroupWise agent.

You can also use desktop shortcuts to start the GroupWise agents. The GroupWise Installation program automatically creates desktop shortcuts for the POA, the MTA, the DVA, and the GWIA. You can easily create a desktop shortcut for Monitor by linking to its target file (c:\Program Files\Novell\GroupWise Server\Monitor\gwmon.exe).

When you start the GroupWise agents as applications, you can use the agent server consoles described in the GroupWise 2012 Administration Guide:

Starting the Windows Agents Automatically as Applications When the Windows Server Starts

After the GroupWise agents are running smoothly as applications, you can configure them to start automatically whenever you restart the Windows server. Use the Windows Task Scheduler to create a task for each agent on the Windows server.

  1. (Conditional) On Windows 2008, click Start > Administrative Tools > Task Scheduler.

    (Conditional) On Windows 2003, click Start > Control Panel > Scheduled Tasks.

  2. (Conditional) If you are not familiar with creating a task using the Window Task Scheduler, refer to your Windows documentation for assistance.

  3. When prompted for the GroupWise program to start, use the following commands to start any GroupWise agents on the Windows server:

    c:\Program Files\Novell\GroupWise Server\Agents\gwpoa.exe
                                                      @post_office_name.poa
    c:\Program Files\Novell\GroupWise Server\Agents\gwmta.exe
                                                      @domain_name.mta
    c:\Program Files\Novell\GroupWise Server\Agents\gwdva.exe @gwdva.dva
    c:\Program Files\Novell\GroupWise Server\GWIA\gwia.exe @gwia.cfg
    
  4. After creating the tasks to start the GroupWise agents automatically, restart the Windows server to verify that the GroupWise agents start successfully.

Starting the Windows Agents Manually or Automatically as Services

If you installed the GroupWise agents as services, you can manage them just as you would any other Windows services.

NOTE:The Monitor Agent cannot currently be installed as a Window service.

For example, on a Windows Server 2003 machine:

  1. From the Windows desktop, click Start > Administrative Tools > Services.

  2. Select the agent service, then click Start.

    The POA service is named after the post office. The MTA service is named after the domain. The GWIA service is named GWIA.

  3. (Optional) Check the status of the agent service by using the Windows Event Viewer:

    1. From Administrative Tools, double-click Event Viewer.

    2. Click Application Log, then sort the log entries on the Source column.

    3. Scroll to the agent service, then double-click a log entry to view information about it.

  4. To configure the agent service to start automatically when the server reboots, right-click the agent service, then click Properties.

  5. In the Startup Type field, click Automatic, then click OK.

NOTE:On Windows Server 2008, the user that starts the GroupWise services must have the Log on as a service right assigned.

When running as services, the GroupWise agents typically do not display an agent console on the Windows server where they are running. Instead, you can monitor the GroupWise agents by using their Web consoles described in the GroupWise 2012 Administration Guide:

Restarting the Windows Agents Automatically

When you run the Windows agents as services, you can use the Windows service Recovery feature to restart them automatically if they stop unexpectedly.

  1. In Windows, click Start > Administrative Tools > Services.

  2. Right-click a GroupWise agent service, then click Properties > Recovery.

  3. Set the Recovery options you want, then click OK.

When you run the Windows agents as programs, you must manually restart them if they stop unexpectedly.

Stopping the Windows GroupWise Agents

How you stop the Windows GroupWise agents depends on how you started them.

Stopping the Windows Agents as Applications

When the GroupWise agents run as applications, you can stop them from their server consoles.

POA:

At the POA server console, click File > Exit.

MTA:

At the MTA server console, click File > Exit.

DVA

From the Windows desktop, click the title bar of the window where the DVA is running, then press F7.

GWIA

At the GWIA server console, click File > Exit.

Monitor:

At the Monitor Agent server console, click Configuration > Exit.

If the GroupWise agent does not respond to Exit, you can close the agent server console window to stop the agent or use the Windows Task Manager to terminate the agent task.

Stopping the Windows Agents as Services

When the GroupWise agents run as Windows services, you can stop them as you would any other Windows services.

For example, on a Windows Server 2003 machine:

  1. From the Windows desktop, click Start > Administrative Tools > Services.

  2. Select the agent service, then click Stop.

    The POA service is named after the post office. The MTA service is named after the domain. The DVA service is named GWDVA. The GWIA service is named GWIA.

Uninstalling the Windows GroupWise Agents

If you move the GroupWise agents to a different server, you can uninstall the agent software from the old location to reclaim disk space.

POA, MTA, and DVA:

Stop the POA the MTA, and the DVA, then run the GroupWise Installation program (setup.exe). On the Install Type page, select Uninstall, then follow the prompts

GWIA:

Stop the GWIA, then run the GroupWise Installation program (setup.exe). On the Install Type page, select Uninstall, then follow the prompts. This deletes most of the contents of the c:\Program Files\Novell\GroupWise Server\GWIA directory and uninstalls the GWIA as a Windows service.

Monitor:

Stop the Monitor Agent. Delete the contents of the c:\Program Files\Novell\GroupWise Server\Monitor directory.