14.1 Linux: Managing the GroupWise Agents

Basic agent monitoring and management is most easily performed on the System Overview page in the Admin console. For instructions, see Making the Most of the System Overview. Refer to the following additional tasks as you maintain all the GroupWise agents on Linux:

14.1.1 Manually Starting and Stopping the Linux GroupWise Agents

This section has information for options you can use to manually start and stop Linux GroupWise agents.

Starting and Stopping the Linux Agents as Services

There are two ways to start or stop Linux agents as services.

Using the grpwise Script

All of the Linux GroupWise agents except the Monitor Agent can be started as services by using the grpwise script. The Monitor Agent uses its own customized grpwise-ma script that works essentially the same way. When the agents run as services, they do not have a user interface.

In the grpwise script, each agent is designated in terms of the name of the domain and post office associated with it, in the following format:

POA:
MTA:
GWIA:
DVA:

post_office.domain
domain
gwia.domain
gwdva

Use the following set of rcgrpwise commands to start and stop the agents as services and verify their status:

rcgrpwise status	Displays the status of the GroupWise agents that are configured to run on the server.
rcgrpwise status agent_location_name	Displays the status of the specified agent.
rcgrpwise start rcgrpwise restart	Starts/restarts the GroupWise agents that are configured to run on the server.
rcgrpwise start agent_location_name rcgrpwise restart agent_location_name	Starts/restarts the specified agent.
rcgrpwise stop	Stops the GroupWise agents that are configured to run on the server.
rcgrpwise stop agent_location_name	Stops the specified agent. If an agent does not respond to the rcgrpwise stop command, you can use the Linux kill pid_number command to stop it.
rcgrpwise print	Lists the contents of the gwha.conf file where the agents are configured. For information about the gwha.conf file, see Automatically Restarting the Linux GroupWise Agents with the GroupWise High Availability Service.

When the agents run without a user interface, you can monitor them by using their agent consoles. See Monitoring the Agents from Your Web Browser.

Using the gwsc Command

You can also manage the GroupWise agents by using the gwsc command, which is short for the gwadminutil services command.

For the gwsc command, each agent is designated in terms of its object name or of the name of the domain and post office associated with it:

POA:
MTA:
GWIA:
DVA:

poa_object_name or post_office_name
mta_object_name or domain_name
gwia_object_name
dva_object_name

Use the following set of gwsc commands to start and stop the agents as services and verify their status:

gwsc -query	Displays the status of the GroupWise agents that are configured to run on the server.
gwsc -query name	Displays the status of the specified agent.
gwsc -start	Starts the GroupWise agents that are configured to run on the server.
gwsc -start name	Starts the specified agent.
gwsc -stop	Stops the GroupWise agents that are configured to run on the server.
gwsc -stop name	Stops the specified agent.
gwsc -list	Lists the agent services that are configured on the server.

14.1.2 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, and library 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:

Ensure that you are logged in as root.
Select a Linux user for the agents to run as, and ensure 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. The user name must not match any local user names on the Linux server.

IMPORTANT:All agents running on the same server must run as the same user.
Change to the groupwise folder under /etc:
```
cd /etc/opt/novell/groupwise
```
Create a new agents folder, and then change to that folder:
```
mkdir agents
cd agents
```
Create a file named uid.conf.
Type the selected user name in the file, for example:
```
gwagents
```
Stop and then start the agents.

While starting as root, the agents automatically change the ownership of the domain and post office folder 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.

IMPORTANT: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.
(Optional) List the agent processes to see that they are no longer running as root.
```
ps -eaf | grep gw
```
Repeat Step 1 through Step 8 on each domain and post office server.

Later on, if you 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 Micro Focus Open Enterprise Server

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

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

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, click the Management Services tab, and then click iManager.
2. To log in to iManager, specify a user name, a password, and a tree.
3. In the left pane, expand Users, and then click Create User.
4. Provide the required information, and then click OK.
  
  The user does not need a password.
  
  IMPORTANT:All agents running on the same server must run as the same user.
Linux-enable the user you just created:
1. In the left pane, expand Linux User Management, and then click Enable User for Linux.
2. Browse to and select the user you just created, and 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.
Ensure that you are logged in as root.
Change to the groupwise folder under /etc:
```
cd /etc/opt/novell/groupwise
```
Create a new agents folder, and then change to that folder:
```
mkdir agents
cd agents
```
Create a file named uid.conf.
Type the selected user name in the file, for example:
```
gwagents
```
Use the following command to grant the user the required rights to the folders that the agents need to access on the local server:
```
rights -f /folder_name -r rwcemf trustee user.context.tree
```
The POA needs access to the post office folder. The MTA and the GWIA need access to the domain folder.
Stop and then start the agents.

While starting as root, the agents automatically change the ownership of the domain and post office folder 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.

IMPORTANT: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.
(Optional) List the agent processes to see that they are no longer running as root.
```
ps -eaf | grep gw
```
Repeat Step 3 through Step 10 on each domain and post office server.

Later on, if you 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 folder that they service. The GWIA creates the uid.run file in its gwia 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, and 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 folder 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 folder to the 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 folder to specify the desired non-root user. Then delete the uid.run file from the folder serviced by the agent.
If you want the agent to run as root again, delete the uid.conf file from the /etc/opt/novell/groupwise/agents folder, and delete the uid.run file from the folder serviced by the agent.

14.1.3 Automatically Restarting the Linux GroupWise Agents with the GroupWise High Availability Service

You can use the GroupWise High Availability Service (gwha), in conjunction with GroupWise Monitor, to detect when a Linux GroupWise agent has stopped unexpectedly and to restart it automatically.

NOTE:On Windows, Microsoft Clustering Services can automatically restart a GroupWise agent service that is not responding. However, on Linux, some clustering environments do not include this capability, so it is provided by the GroupWise High Availability Service.

The GroupWise High Availability Service is installed automatically. After you enable it, it automatically starts when your server starts.

The High Availability Service relies on the Monitor Agent to detect when a Linux GroupWise agent is no longer running. The Monitor Agent notifies the GroupWise High Availability Service of any problem. Then the GroupWise High Availability Service then issues the command by using the grpwise script 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.

NOTE:You can use either the Linux Monitor Agent or the Windows Monitor Agent to monitor the Linux GroupWise agents. However, you cannot use the GroupWise High Availability Service to restart the Windows GroupWise agents.

Reconfiguring the GroupWise High Availability Service (Optional)

The default configuration of the High Availability Service is often appropriate, but you can optionally edit its configuration files to customize its functionality:

Editing the gwha File to Change the Port Number (Optional)

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.

IMPORTANT:The GroupWise High Availability service must use the same port number on all servers where you want it to restart the GroupWise agents.

In a terminal window, become root by entering su - and the root password.
Edit the gwha file in an ASCII text editor.
Change the port number as needed.

IMPORTANT:Do not change any other options in this file.
Save the file and exit the text editor.
Continue with Editing the gwha.conf File to Enable TLS and Customize Agent Management (Optional).

or

Continue with Enabling the GroupWise High Availability Service.

Editing the gwha.conf File to Enable TLS and Customize Agent Management (Optional)

The interaction between the GroupWise High Availability service and the GroupWise agents is controlled by the following file:

/etc/opt/novell/groupwise/gwha.conf

You can reconfigure the following functionality:

Enable TLS between the High Availability Service and the Monitor Agent.
Change the length of time between when the grpwise script issues the command to start an agent and when the script displays a message indicating that the agent has started.
If you changed the port number in the /etc/xinetd.d/gwha file, make the corresponding change in the gwha.conf file.

At the top of the gwha.conf file, in the [gwha] section, is a section for configuring TLS for communication between the GroupWise High Availability service and the Monitor Agent. After the [gwha] section are sections for each agent that is configured to run on the server, as shown. The headings for the agent sections match the agent designations listed in Starting and Stopping the Linux Agents as Services.

[gwha]
TLS       = 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 reconfigure the GroupWise High Availability service in the gwha.conf file:

In a terminal window, become root by entering su - and the root password.
Edit the gwha.conf file in an ASCII text editor.

(Conditional) If you use TLS, fill in the following fields in the [gwha] section:

[gwha]
TLS      = yes
key      = file_name.key
cert     = file_name.crt
password = password

(Conditional) If you changed the port number for the GroupWise High Availability service, as described in Reconfiguring the GroupWise High Availability Service (Optional), 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.
(Optional) If you want to control how the grpwise 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.
Save the file and exit the text editor.
Continue with Enabling the GroupWise High Availability Service.

Enabling the GroupWise High Availability Service

Starting in SLES 12, SLES supports systemd as a replacement for xinetd. In SLES 15, xinetd is not supported at all. Because of this, when you install GroupWise 18.3 or a later version on SLES 12 or on SLES 15, the install places gwha.socket and gwha@.service in /usr/lib/systemd/system. On SLES 12, you can still use the xinetd process to enable GWHA. On SLES 15 you must use the systemd process to enable GWHA.

Enabling GWHA on xinetd (SLES 12)

To enable GWHA on xinetd:

In YaST, click Network Services > Network Services (xinetd).
(Conditional) If necessary, select Enable to activate the list of services.
Scroll down to the gwha line, select it, and then click Toggle Status (On or Off) to change the status to On.
Click Finish.
Repeat Step 1 through Step 4 on all servers where you want the GroupWise High Availability service to restart the GroupWise agents.
Continue with Creating a GroupWise High Availability Service User.

Enabling GWHA on systemd (SLES 12 and 15)

To enable the GWHA service on systemd when the server is rebooted, open a terminal and run the following command:

systemctl enable gwha.socket

NOTE:If you previously had xinetd enabled on SLES 12, you must disable it before enabling systemd.

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.

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

You might name it gwhauser.

IMPORTANT:Use a local user account for use only by the GroupWise High Availability service. Do not use a Micro Focus Linux-enabled user. Do not use root.
Create the same user on each Linux server where you want the GroupWise High Availability service to restart the GroupWise agents.
On each Linux server, configure the gwha.allow file for the new user:
1. Change to the following folder:
```
/etc/opt/novell/groupwise
```
2. Edit the gwha.allow file in an ASCII text editor.
3. Specify the user that you created in Step 1.
4. Save the file and exit the text editor.
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 Monitor Agent to communicate with it, and then test it to ensure that you can rely on it in the future.

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

Configuring the Linux Monitor Agent

Install the Linux Monitor Agent.

For installation instructions, see Setting Up GroupWise Monitor.
Configure the Linux Monitor Agent with the --hauser, --hapassword, and --hapoll startup switches.

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.

For more information, see Using Monitor Agent Startup Switches in the GroupWise 18 Administration Guide.
1. In YaST, click System > /etc/sysconfig Editor.
2. Expand Network > Mail > GroupWise.
3. Click GROUPWISE_MA_OPTIONS.
4. In the Setting field, set the --hauser and --hapassword switches for the user that you created in Creating a GroupWise High Availability Service User.
  
  HINT:An easy way to create the string is to copy the example at the bottom of the Description paragraph and replace username and password as needed.
5. In the Setting field, set the --hapoll switch for the number of seconds in the poll cycle on which the Monitor Agent contacts the GroupWise High Availability Service to provide agent status information.
6. Click OK to save the settings.
7. Click OK again to save the change.
8. Exit YaST.

Start the Monitor Agent.

                    rcgrpwise-ma start

Continue with Testing the High Availability Service.

Configuring the Windows Monitor Agent

Install the Windows Monitor Agent as either an application with a server console on the server or as a Windows service without a user interface on the server.

For installation instructions, see Setting Up GroupWise Monitor.

NOTE:The Windows Monitor Agent provides a server console that is not available on Linux. For more information, see Comparing the Monitor Consoles in the GroupWise 18 Administration Guide.
Configure the Windows Monitor Agent with the /hauser, /hapassword, and /hapoll startup switches.

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.

For more information, see Using Monitor Agent Startup Switches in the GroupWise 18 Administration Guide.
(Conditional) If you installed the Windows Monitor Agent as an application:
1. Create a batch file similar to the following example:
```
c:\Program Files\Novell\GroupWise Server\Monitor\gwmon.exe
     /hauser-gwha /hapassword-gwha /hapoll-60
```
2. Create a desktop icon for running the batch file.
3. To start the Monitor Agent, run the batch file.
(Conditional) If you installed the Windows Monitor Agent as a Windows service:
1. In the Control Panel, click Administrator Tools > Services.
2. Right-click GroupWise Monitor, and then click Properties.
3. In the Start Parameters field, specify the required Monitor Agent startup switches, and then click OK. For example:
```
/hauser-gwha /hapassword-gwha /hapoll-60
```
4. To start the Monitor Agent, right-click GroupWise Monitor, and then click Start.

Testing the High Availability Service

Stop one of the Linux agents, as described in Starting and Stopping the Linux Agents as Services.
Check the status of the agent you stopped to make sure it is stopped.
Wait for the next Monitor Agent polling cycle.

You can check and, if necessary, change the Monitor Agent polling cycle in the Monitor Agent console. Click Preferences, and then scroll down to the HTTP Settings section.
After the polling cycle has passed, check the status of the agent again.

The agent that you stopped should now be running again.

14.1.4 Using the Linux GroupWise Agent Log Files

Agent status messages and error messages are written to the agent log files (mmddagent.nnn) in agent-specific subfolders of the following folder:

/var/log/novell/groupwise

The log file name includes the month and day when it was created, the name of the agent, and an incrementing extension to accommodate multiple log files on the same day.

The agents also maintain a symbolic link to a file named agent.currentlog, where agent is the name of the agent object in the Admin console. This link points to the current agent log file, regardless of the date and incrementing extension of the actual agent log file name. This facilitates monitoring the current agent log file using the tail command.

NOTE:The agent.currentlog symbolic link is not available for the DVA log files.