Novell Home

In the first part of this series, I described how Novell IS&T was benefiting from running GroupWise on Open Enterprise Server on Linux and described how to use the GroupWise Server Migration Utility to migrate a GroupWise post office from Windows or NetWare to Linux.

The GroupWise Server Migration Utility was not yet in beta at the time of writing, and now additional functionality has been committed and is in the shipping product. In this article, I describe how to use the utility to migrate GroupWise domains, Internet Agents and WebAccess agents to Linux.

The migration utility allows an administrator from a Windows workstation (a Linux version is planned for the future) to connect to the source server (Windows or NetWare) and to the destination Linux server and easily migrate the GroupWise data, install agents and perform any necessary case conversions on the GroupWise data files.

If you haven't read the first article, which was published online at, you should read it before you read this article. It explains in detail the benefits we as an IT department are experiencing by running GroupWise on Linux, some of the challenges we faced in moving to Linux and how we addressed them, and a look at running the migration utility to migrate post offices to Linux. All of that information applies to migrating domains, Internet agents and WebAccess agents; however, I will not cover it in detail here. This article gives additional detail about how to add and configure agents for migration.

> Migrating GroupWise Data
After meeting the prerequisites to run the migration utility and supplying information about the source and destination servers, the migration utility requires you to define which GroupWise components you want to migrate. (See Figure 1.)

The Auto-Detect feature was designed for detecting default installations of GroupWise agents on NetWare servers. If your servers have different file locations than the default location of SYS:\SYSTEM, then this feature won't help you much and you will have to add components manually.

When you click on Add Domain, or Add Post Office, enter these three paths in the dialog that appears (See Figure 2.):

  1. the source database path
  2. the existing startup file path
  3. the destination path

Note: The Add Agent button does not appear until you specify a domain to migrate.

Select the source database path by browsing to the location of the GroupWise database files, either wpdomain.db for a domain or wphost.db for a post office.

By specifying the existing startup file path, any configuration options in the startup file will be duplicated where applicable in the new startup file on the destination Linux server. If a startup file is not specified, a new one will be created. If the migration utility doesn't interpret the startup file properly, simply omit the path to the startup file and proceed.

A default destination path is automatically populated once you select the source database path. You may edit this path to be what you desire. By default the path is defined as /var/opt/novell/groupwise/mail/[directory]. The utility automatically places the directory name of the source database directory as the destination directory.

Note: The migration utility will allow you to migrate one domain and its agents or one post office and its agent at a time. (See Figure 3.)

> Adding Agents
The Add Agent feature allows you to add any or all Internet Agent(s) or WebAccess Agent(s) associated with a particular domain to be migrated along with the domain and its message transfer agent. (See Figure 4.)

Note: The migration utility cannot migrate a WebAccess application. You must reinstall the WebAccess application on the destination server using the GroupWise Linux CD Setup program. I'll show you how later in this article.

The Add Agent feature installs the necessary agent software on the destination server and creates a new startup file containing the configuration information from the startup file on the source server. Because the startup files for these agents specify which gateway definition is serviced by the agents, you must specify the location of the source startup file to migrate these types of agents.

Migration of Agent Log Files

Rather than letting the migration utility copy the agent log files, you might want to archive them to a backup server for reference purposes before migrating a domain and its agents. Removing them will save some time during the migration process as the agent will no longer access them after the migration. To locate an agent's log files, check ConsoleOne for the path. The default locations of the log files are listed below.

Default Log File Locations
Message Transfer Agent domain\mslocal. If you use the /work startup switch, the log files will be in the mslocal directory in the indicated directory. The message logging files are in the mslocal\mslog directory either under the domain or the directory indicated by the /work startup switch.
GroupWise Internet Agent domain\wpgate\gwia\000.prc
WebAccess Agent domain\wpgate\< webacc agent name >\000.prc

> Agent Startup Files
By default, the name of the Internet Agent's startup file is gwia.cfg and it is normally located in the agent startup directory where the gwia executable is installed. Previously, it was placed in the gateway directory.

The WebAccess Agent startup file is normally named < gateway name >.waa and is also located normally in the agent startup directory where the gwinter executable file is.

Once you have successfully added the agents, they will display in the Component to Migrate dialog.

> Agent SSL and Key Files
After specifying agent information and proceeding with the migration, the utility will prompt you for information about SSL certificates in use by the agents. GroupWise agents can use SSL keys to encrypt data transmissions. It is common to provide an SSL key for the Internet Agent to secure SMTP e-mail connections on the Internet.

The migration utility allows you to use existing SSL files or to point to new files. You might want to use an existing SSL file if it is using a DNS hostname that will be used on the new server. Otherwise, if the DNS hostname on the new server is different, you should create a new certificate. See the GroupWise documentation for creating SSL certificates at

To migrate the SSL certificate and key file, simply browse to the files and select them. (See Figure 5.)

> Internet Agent Port Conflict
When migrating the GroupWise Internet Agent to Linux, it is necessary to make sure another SMTP agent is not running on the Linux server. By default on SUSE Linux and Open Enterprise Server Linux, the postfix smtp agent runs to allow mail delivery of server notifications. Postfix is configured to listen only on the localhost IP address (

You have two options. (See Figure 6.) You can choose to bind the Internet Agent to listen only on the server's IP address or you can disable the postfix agent and allow the Internet Agent to listen on all addresses including the localhost address. If you need postfix to listen on multiple addresses, you can bind multiple IP addresses to the server and configure postfix to listen on IP addresses that are different than the IP address the Internet Agent uses. This type of configuration is beyond the scope of this article; however, information on configuring postfix is available at To disable posftix, execute the command:
chkconfig postfix off.

> Migrating Data
At this point, the migration utility is now ready to migrate data. If you want to proceed, you can down the selected agents for the domain and proceed with the data migration. Otherwise, you can leave the agents running and proceed with a trial migration of the data.

Managing the GroupWise Agents on Linux

The GroupWise Setup installs a script in /etc/init.d named grpwise. This script allows you to manage the GroupWise agents by starting, stopping and viewing the status of the scripts. For a quick reminder of the command options, simply execute the script with no parameters. You will see the following output:

Usage /etc/init.d/grpwise {start|stop|status|print} [object]

To see the names and types of the agents that have been configured on a particular server, use the print option:
/etc/init.d/grpwise print

This will display the contents of the script's configuration file, (/etc/opt/novell/groupwise/gwha.conf). Here are two examples from the script file, one from before the migration utility has completed, the other from after.
  gwha[0] := no
  agent[0] := [@webamer.waa]
  agent[1] := /opt/novell/groupwise/agents/bin/gwinter
  agent[2] := /etc/init.d/grpwise
  agent[3] :=
  agent[4] := 2
  agent[5] := 10
  agent[0] := [web]
  agent[1] := /opt/novell/groupwise/agents/bin/gwinter
  agent[2] := /etc/init.d/grpwise
  agent[3] :=
  agent[4] := 2
  agent[5] := 10

In the case before, the startup file name is used as the name of the agent [@webamer.waa]. In the case after, the agent's name has replaced the startup file name [web]. To start the agent for the "Web" WebAccess agent, use the following command:
/etc/init.d/grpwise start web

Syntax for all other defined agents follows the same pattern. If needed, you can manually edit the gwha.conf configuration file to customize it.

> Things to Consider
The migration utility will simply copy all of the files located under the domain directory structure that you defined earlier. If you have large quantities of unessential files located under this directory, you might want to delete or remove those files before proceeding. Some good candidates are logfiles and also message logfiles. For instance, on our servers at Novell, we typically keep at list 1GB of logfiles per agent. The Linux agents store the logfiles in a different location than on other platforms; however, the migration utility does not support moving them to the proper location. Therefore, they are not accessible to the agents. If you move them to another directory on the server that is not located under the domain directory structure, the migration utility will not copy them, thus shortening the amount of time required to migrate data.

> Migration
Once you are ready to proceed, you have the chance to review all of the migration information as presented in the Migration Summary dialog. Clicking on Migrate will cause the migration utility to copy the necessary software packages to the Linux server and install them. Then it will connect to the source server and copy the GroupWise data. It will then install and configure the GroupWise agent and properly configure the GroupWise agents to run on Linux.

Installing and Managing the WebAccess Application on a Linux Server

The GroupWise Server Migration Utility does not support migrating the WebAccess application, only the WebAccess agent. This section describes the essential steps to do this and also gives tips and information not included in the documentation. For complete instructions on how to do this, see the section Migrating the WebAccess and WebPublisher Applications to Linux in the GroupWise 7 Installation Guide at

The process to install and configure the WebAccess application requires the following:
GroupWise Installation CD for Linux
Path to the WebAccess agent gateway directory on the Linux server

Example: domain/wpgate/< web>
LDAP server IP address and Trusted Root certificate for the eDirectory tree if SSL/TLS is required to connect to the LDAP server.
Note: This can be exported from ConsoleOne or iManager from the SSL CertificateDNS-< server> object. Export the Trusted Root Certificate for this object.
To install the application, run the GroupWise install from the files on the CD either by mounting the CD on the Linux server or copying the files directly to the server. If you copy the files, you must change the file permissions using the following command on the copied files in order to enable the install scripts to run properly:
chmod -R 755 *

Install the WebAccess application and then configure it. The installation will either use the Novell version of the Apache Web server and Tomcat servlet gateway if installing to Open Enterprise Server on Linux or it will install a GroupWise specific version of Apache and Tomcat if using SUSE Linux Enterprise Server or a different distribution of Linux. The Apache files are installed under /var/opt/novell/httpand /etc/opt/novell/http. The Tomcat files are installed under /var/opt/novell/tomcat4and /etc/opt/novell/tomcat4. It will also generate a self-signed certificate allowing an SSL connection to WebAccess.

Run the configuration option. It will ask a series of questions. First, it asks for the path to the gateway directory. It will also ask for the paths to the Apache and Tomcat home directories. Accept the default paths. It next asks for the LDAP server IP address, user name, password, and path to the trusted root SSL certificate used by the LDAP server. The user you specify must have Create rights to the container where you will place the WebAccess application objects.

It next asks for the context where to create the application objects. Choose a different container than the domain as it will overwrite the existing objects and you will lose any configuration setting changes made. Note: The install gives a sample syntax for the container object as cn=domain,o=container which is correct if you are placing the objects in the domain container; however, the correct syntax for an organizational unit container will be ou=sub,o=container. After providing this information, the install will create the WebAccess application objects in eDirectory and create the necessary configuration files on the server.

To launch the application, simply restart Apache and Tomcat. On Open Enterprise Server for Linux, you use the apache2 and novell-tomcat4 scripts located in the /etc/init.d directory to restart these applications and load the WebAccess application.
/etc/init.d/apache2 restart
/etc/init.d/novell-tomcat4 restart

Finally, apply any needed configuration changes to the WebAccess application objects using ConsoleOne and then restart Tomcat to apply the changes. Test logging in to make sure everything works properly and GroupWise WebAccess on Linux will be ready to go!

> Post Migration Tasks
After the data migration portion is complete, don't exit the migration utility as it has not completed its work. The agents will not be configured properly on the Linux server unless you allow the migration utility to finish. You need to use ConsoleOne to connect to the domain database on the new server and change the path to the domain and also change the IP addresses for the agents migrated. Any other paths defined, such as logfiles or certificate files need to be removed or modified as well. The Help files for the migration utility give detailed information on the items you should consider. If you are performing a trial migration, use the agent startup file to make temporary changes to agent settings and don't use ConsoleOne. After modifying the IP addresses for the agents, let the migration utility start the GroupWise agents to complete the configuration of the agents. If you don't, the scripts installed on the Linux server to manage the GroupWise agents won't work properly. In addition, you need to launch the Message Transfer Agent to replicate the network IP address changes to the rest of the GroupWise system. (See Figure 7.)

If you migrated a WebAccess agent, and want to migrate a WebAccess application, install the WebAccess application using the GroupWise installation CD and then configure it manually. See Installing and Managing the WebAccess Application on a Linux Server for information on how to do this. To manage the GroupWise agents on Linux, you can use the /etc/init.d/grpwise script. See Managing the GroupWise Agents on Linux for information on how to use this script.

> Summary
The GroupWise Server Migration Utility greatly simplifies the process of migrating GroupWise post offices, domains and their respective agents from NetWare or Windows to Linux. It is a powerful tool that helps GroupWise administrators leverage the reliability and power of Linux to make GroupWise even more reliable and scalable than ever.

The utility was released in October 2006. To download check N

© 2015 Micro Focus