Novell is now a part of Micro Focus

Moving GroupWise Systems

Novell Cool Solutions: AppNote

Digg This - Slashdot This

Posted: 6 Sep 2006


There are many instances where you would want to move an entire GroupWise system from one server to another, such as hardware upgrades. Your old Pentium Pro system isn't feeling too well lately, and it's high time to upgrade to a newer, faster, higher-capacity (not to mention vendor-supported) computer system. Or you may find that it is time to migrate your single-server GroupWise system to a clustered server platform, to add another layer of fault-tolerance for your email and groupware solution.

In most cases, migrating your GroupWise system is not a task for the faint of heart, or for the inexperienced. If your organization depends on email and calendaring services as part of the lifeblood of the day-to-day operations, you're better off getting someone who has done this before. If you don't have the experience yourself, and if hiring an experienced outside consultant isn't a viable option for you at the moment, then it will benefit you to at least read up on the process as much as possible.

For the most part, it is essential to understand the components that make up your GroupWise messaging/calendaring system, and what parts communicate with what other parts, and how that communication takes place.

Most GroupWise admins already know that the basic GroupWise system consists of a Message Transfer Agent (MTA), a Post Office Agent (POA), and usually one or more gateways, such as the Internet Agent (GWIA) and WebAccess Agent (WAA). That's basic, and it's also apparent, since each agent has its own screen (on the NetWare platform), or its own service, and can be viewed in its own window (on the Windows platform).

Each of these agents has its own set of database and configuration files as well, which must be considered when attempting to move the GroupWise system to another server. The configuration files (and configuration parameters that are contained in eDirectory) need particular attention during migration, since they dictate how each of these agent expect to communicate with all of the other agents.

Big Moves

An excellent overview article that sums up the GroupWise migration process is provided by Gregg Hinchman in his "Consultant's Corner" article ( There you can see that he begins with changing the configuration parameters for the GroupWise agents in eDirectory through ConsoleOne (which, in most cases, also automatically changes the corresponding parameters in the text-based configuration files for those agents). There are UNC paths for the Software Distribution Directory and Libraries and log file paths to be changed, and IP addresses for the MTA and POA, which need to correspond to the new server.

The GroupWise data itself then has to be moved to the destination server (or servers), after the GroupWise agents on the original server are shut down. This can often be just a simple file copy, but can also be accomplished with something like the Novell Server Consolidation and Migration Toolkit, or using your data backup system to restore the data to the new location.

Note: the GroupWise messaging system is not designed to be "married" to the server it was originally installed upon. Therefore it is not essential to try to migrate it to a new server with exactly the same "identity" - server name and IP address - as the original server. In this sense, the GroupWise agents run somewhat independently from the host operating system. This feature allows you to migrate the GroupWise agents to a different server, or multiple servers, so as to separate different agents to different servers, or to migrate to a server cluster.

This type of modularity also allows you not only to migrate components of a GroupWise system (domains, post offices, gateways) from one NetWare server to another, but also to migrate a GroupWise system from a NetWare platform to a Windows platform, or vice-versa, or even to migrate to a Linux platform. To view articles on moving your existing GroupWise domains and post offices to Linux, see TID 10099947 and TID 3407855.

The GroupWise agents need to be installed on the new server to complete the migration. While it is possible, particularly on the NetWare platform, to merely copy all of the relevant GroupWise NLMs from the old server to the new, it is always recommended to perform a fresh installation of the GroupWise agents to the new server, to insure that they will be correctly installed and configured.

Finally, in the migration process, is the verification process, where we find out if we've installed and configured everything correctly (or not). It is always best to manually launch one agent at a time, and determine if it is loaded correctly, and then move on to the next agent. Typically, we proceed from the "core" outward - first testing the MTA(s), then the POA(s), then the gateways (GWIA, WebAccess).

The primary consideration for each agent is whether it loads correctly - meaning, that the agent can load and read its own database and configuration files. The second consideration is whether each agent can correctly communicate with the other agents, so that messages can flow from one to another. Usually, when the migrated agent cannot load correctly, it is due to an incorrectly configured UNC path, so the agent cannot find and load its database files as it should. When the agents do correctly load, but cannot communicate with one another, it is usually due to incorrectly configured links, so that the agents don't know exactly how to find and communicate with each other.

As well as checking all of the GroupWise parameters - UNC paths, TCP/IP addresses, link configurations, etc. - in ConsoleOne, it always pays to examine the text-based configuration files that the agents use to load. For the MTA, it is typically <MTAname>.mta, by default, and for the POA, <POAname>.poa. But when you have experienced upgrades and configuration changes, you'll find that the actual config file being used could have been incremented to ".po1", ".po2", etc. (for the POA), and ".mt1", ".mt2", etc. (for the MTA). Check the GRPWISE.NCF (on the NetWare platform) for the name of the actual config file being used. For example:

Load SYS:\SYSTEM\gwmta @domain.mt1
Load SYS:\SYSTEM\gwpoa @mainpost.po1

Another good overview article on moving an entire GroupWise system is TID 10024917.

Small Moves

However, there are circumstances where you don't really want to move the entire GroupWise system, or even entire post offices to another server - at least, not all at once. In some instances, we would want to perform a gradual move of users to a new post office, or perhaps split an existing post office into two by moving selected groups of users to a newly created post office, and leaving the rest alone.

We may also wish to move a single GroupWise server to a clustered server environment, but due to production constraints, we choose to perform a gradual move of users, rather than an "all at once", or "all or nothing" scenario.

Sometimes it is like the old adage of pulling off an adhesive bandage - sometimes you want to ease it off, to minimize the pain at any particular point, and sometimes you just have to grit your teeth and rip it off all at once, to get it over with and minimize the amount of time that is painful.

And then, in some instances, there's a long history with a particular GroupWise system of installations, upgrades, patches, components that we installed, but didn't need, and then perhaps uninstalled. These conditions can make it undesirable to try to move the entire system "as is" to a newer server, or perhaps to a cluster, if we are seeking higher availability. Sometimes it is beneficial to start anew with a clean post office database and then begin to move our GroupWise users over from the old to the new.

In these cases, setting up new post offices and domains and then performing a "live move" of users would be the preferred method.

The GroupWise Cluster Scenario

Let's look at a scenario where we perform such a live move of GroupWise users from a single server to a new GroupWise cluster.

Obviously, the first step in this endeavor would be to create the cluster environment itself. Let's start with a NetWare cluster. The basic requirements are at a minimum two servers, a shared disk storage system, and the NetWare operating system.

If we are in a larger data center environment, then we may have the benefit of having a Storage Area Network (SAN), typically connected to servers via fibre channel and host bus adapters (HBAs). The general fibre channel connections and configurations are fairly standard among vendors, but the specific methods of installing and configuring the appropriate drivers at the server end, and configuring the shared disk storage, or Logical Unit Numbers (LUNs), at the storage end, will vary a bit according to vendor.

Essentially, we determine how much storage will be assigned to the servers, and assign that storage group (the nomenclature varies according to vendor) to the particular servers in the clusters. In the end, the assigned LUNs appear to the server operating system as if it is merely an available single disk or array, of whatever size we have specified.

Another option for shared storage uses the iSCSI protocol and Ethernet adapters, instead of the more expensive fibre channel cabling, switches, and host bus adapters. Because standard gigabit Ethernet switches and adapters and CAT-5 cabling are used, the iSCSI SAN architecture can be far less expensive to implement. There is still the central storage unit(s), with its disk array(s), and dedicated storage operating system, but it is attached to servers via Ethernet, rather than via fibre channel.

The iSCSI software initiator is built into NetWare 6.5, by the way, and merely needs to be configured to communicate with iSCSI targets.

A third option for shared storage is dual-attached standard SCSI storage, but this limits the implementation to only two hosts, and is thus not scalable.

Once we have NetWare installed on at least two servers, and have the shared storage properly configured, the servers should each be able to recognize the raw storage, or LUN, and be able to create NetWare partitions from this storage. However, we will wait until the NetWare clustering software is installed and configured before creating our NetWare volumes. This ensures that the volumes we create are clusterable - able to be mounted on either (or any) member (or node) in the cluster.

First, we follow the standard procedures for installing Cluster Services (see Installation and Setup in the GroupWise documentation) for NetWare servers. When we reach the point where we are asked if the cluster has shared media (answer "Yes"), here is where we discover whether we have our shared storage correctly configured. If all is well, then the Cluster Services creates the 8 MB cluster partition (sometimes called the "Split Brain Detector") on the shared LUN. If the installation routine fails to detect the shared media, then usually we have a problem with the shared storage configuration.

Once Cluster Services is correctly installed, we can then simply use NSSMU at the NetWare console to create the clustered partition, pool, and volume upon which we wish to place all of our GroupWise information - the NLMs, the databases, configuration files, and all.

If you are relatively new to clustering, one important concept you need to have is to separate the server from the services. For every clustered resource (or service), all of the necessary files, whether executables, databases, or configuration files, need to be completely independent of the operating system. Remember: the goal of clustering is to keep the services alive, even when the server has failed.

For GroupWise clustering, this means that all of the GroupWise components need to be installed on the clustered volume. So the default installation paths, such as SYS:\SYSTEM, have to be superseded in favor of the shared volume. For more information, see Novell Cluster Services in the GroupWise documentation.

As an example, let's say we create two cluster nodes, named GWCL-A, and GWCL-B, for the purpose of a GroupWise cluster. We create a shared cluster volume, called GWMAIL, with an IP address of, upon which we want to install all of the GroupWise software. For the Acme organization (which manufactures all of those cool gadgets for Wiley Coyote), we want to create a GroupWise domain called ACME2, and a post office called POST2.

During the GroupWise installation, we are prompted for the names and file locations for the domains and post offices we wish to create. Using this example, I typically would specify something like the following parameters:

	Post Office:	POST2		GWMAIL:\POST2

Thus the GroupWise agents are configured with the IP address of the cluster volume, which can fail over to any node (server) in the cluster. And the GroupWise databases, as well as the executable NLMs and configuration files, all reside on the same cluster volume. This makes the GroupWise services portable - able to float from one cluster node to another, independent of the host operating system.

Making Your Move

So enough about clustering - what about moving the GroupWise users to the clustered servers? If we were planning to do the all-at-once database migration of the GroupWise system, as in the aforementioned articles, we would have copied the existing databases from the previous GroupWise server (after shutting down all the agents), and then re-installed the agents on the cluster, pointing them to the new locations. Then we would also have to carefully modify all the appropriate UNC paths, IP addresses, link configurations, and such, both in the corresponding ConsoleOne objects, and also in the text-based configuration files.

As we mentioned before, if we've done all our work correctly, we launch the agents (this time from the cluster resource script) at their new location on the cluster servers, in the proper order, thus "waking up" the GroupWise system. If all our ducks are in a row, then the system will work properly - the clients will be able to communicate with the post office, the post office with the domain Message Transfer Agent (MTA), and the MTA with the gateways.

But in the second scenario, where we want to make live moves of GroupWise users in a phased or gradual fashion, we would install a new, secondary domain, and its MTA, and a new post office, on the cluster resource (using the clustered volume and its IP address). The secondary domain holds a replica of the GroupWise domain database. (By the way - it is always recommended to have a secondary GroupWise domain in all but the smallest single-server environment. Its replica can always be promoted to primary in case that the primary domain database somehow is lost, due to corruption or server failure.) This also gives us a new, pristine (empty) post office, to which we can now begin moving users according to our needs.

In the live-move scenario, the original GroupWise server and system never have to be brought down; indeed, they need to remain up so that the secondary domain and post office can be integrated into the system. This also gives us the chance to perform a little proof-of-concept and pilot testing of the move process, to ensure that everything is working correctly. It's much better to find out, using test user accounts, that a particular function is not working, than to find out only after moving ALL of the users, and then having to face moving everything back to the way it was, at square one.

This can be especially true when working with third-party gateways. If all of their features work correctly with the test user accounts, and with the real pilot user accounts (typically, the usual IT staff guinea pigs), then we can have increased confidence that it will work for the rest of the users. In any case, it's always nice to have some indication of successful working, before we commit to an all-at-once, do-or-die type of server move.

For the GroupWise live-move operation, once we have assured that the secondary domain and post office are correctly configured and working with all parts of the system, we can begin to move the users according to our desired schedule. We can accomplish the moves using ConsoleOne by selecting individual users or highlighting multiple users, right-clicking and selecting Move, and then browsing to and selecting the new post office to which we want to move them.

The live move uses the configured TCP/IP connection between the post offices (POAs) to move the user account, all of the user's email, and all associations (proxy rights, shared folder access, and such). However, some client options and rules might be lost in the transfer and need to be re-created, so it is best to check those before and after a move.

Move Considerations

When there are GroupWise resources that are owned by users who are being moved, GroupWise needs to know what to do with these resource ownerships, which are (by design) post-office-specific. It is usually a good idea to perform an assessment of all the resource objects prior to the move operation, to determine a good plan for handling resource ownership. If resources are to remain in the original post office (i.e., not all users will be moved), then selecting a new owner for the affected resources will resolve that issue. If the resource, as well as its owner, will also be moved to the new post office, we can usually select a user account to which to temporarily assign ownership, until both the resource and the original owner are successfully moved to the new location.

Also, most administrators prefer to run GroupWise maintenance tasks on both the original post office and even on the individual user accounts targeted for the move. Especially, cleaning out all the garbage - deleting obsolete messages and emptying the Trash - means that there is less information that needs to be moved to the new location. That's always a good idea; after all, if there are any problems with the user account, you wouldn't want to merely transfer those problems to the new post office. They can also cause the move operation to hang up in some instances.

In addition (this would seem to be obvious), the individual user who is being moved should close the GroupWise client, and even GroupWise Notify, during the move operation. While technically the live move can happen while the user is sending and receiving emails (that's why they call it "live"), in many cases the open client can hold certain operations open, and the move will never complete until the user closes the GroupWise client. I would just prefer to have the user out of the account until it is successfully moved - then I can know for sure which post office is holding the user's email.

Some GroupWise admins choose to initiate a move of a batch of users at the end of the production day, and then monitor the success (we hope) when they return the next day. But some will perform the move of VIP (power) users one at a time, just to be able to carefully monitor and ensure the success of each individual user account move.

For good step-by-step instructions on moving GroupWise accounts to a new post office, see Moving GroupWise Accounts in the GroupWise 6.5 Administration Guide.

When the GroupWise client launches for a user that has been moved, it first attempts to attach to the original post office, where it last successfully connected (hopefully, by IP address and TCP port - you are in client/server mode, aren't you?!). The original post office has been made aware of the move, and automatically redirects the client to the destination post office, to where the user was moved. If you were to watch the client connection carefully, you can see this redirection happen. Once successfully connected, the client then remembers this new successfully-connected address.

If something isn't configured correctly, and the GroupWise client cannot find to where it needs to redirect, it will try to fall back on the default DNS names of ngwnameserver or ngwnameserver2. This is a good reason, if you have any control at all of your local DNS system, to have those two A-records implemented to point to your GroupWise post offices, to assist the client to find the GroupWise servers. As last resort, they can be implemented in a local hosts file on the workstation.

After moving users, you may find that some users might have the moved user's old address (GroupWise user ID) in their Address Book's Frequent Contacts list. Then, if the sender types the moved user's name in the To field (rather than selecting it from the system address book), GroupWise pulls the old address stored in the Frequent Contacts list instead of the new address, and the message bounces back as being undeliverable. The POA will automatically resolve this issue when it performs its regular nightly user upkeep to validate that all addresses in a user's Frequent Contacts list are valid addresses in the system address book. So this temporary lookup failure should pass.

Monitoring Moves

During the process of moving users, you can monitor the status of the move process in ConsoleOne by selecting a Post Office or Domain object and clicking Tools | GroupWise Utilities | User Move Status. There you can see the user accounts for which you have initiated the move operation, and their last move status. On occasion, a move operation can appear to be hung, and clicking the Retry/Restart button can get it going again. When the system deems that any of the operations (such as Retry/Restart or Force Complete) would not be safe to perform, then those buttons will be grayed out (inactive).

You can also see the user move activity on both of the source and destination post offices agents' (POAs') activity screens on the server. However, if there is a lot of other activity, such as the normal sending and receiving of emails, you may not be able to read the activity screen fast enough to get a clear idea of the progress. If all is quiet on the POA (such as on a new post office to which you are migrating users), you might be able to view the play-by-play activity of the move, to get a good feel about the process and how it is progressing.

When the user (or batch of users) has finished the move process, you will see an empty list in ConsoleOne's User Move Status window (which does not automatically refresh - you'll need to click Refresh or close and re-open it to see updates). On the POA activity screen, there will also be a final "move completed" message that appears for each user account, if you happen to be watching it as it passes by. In the interim, you might observe several different status messages:

  • Destination post office updated
  • Source post office updated
  • Moving mailbox information
  • Sending mailbox inventory list
  • Send item request
  • Retry mailbox item retrieval
  • Completed retrieving items
  • Move completed

This shows you the process that GroupWise goes through to execute the move operation. Once all of the user's mailbox items have arrived in the destination post office, then finally the user's original account in the source post office is deleted and the user move is entirely complete.

Resources can be moved in essentially the same way as the users. If resources were temporarily re-assigned to alternate owners to facilitate the user moves, they can be again re-assigned to their original owners, after both have been moved to the same post office.

So if you find yourself "making moves" in your GroupWise system, I hope this can help you make all the right moves. May all your moves be happy ones!

Novell Cool Solutions (corporate web communities) are produced by WebWise Solutions.

© Copyright Micro Focus or one of its affiliates