GroupWise Migrations – A Better Way


Why migrate?

A GroupWise migration is needed when GroupWise must run on a different server. Historically this has occurred when a GroupWise system was not virtualized and a hardware upgrade was needed or when GroupWise had to be run on a different OS, for example, migrations from NetWare to a supported platform. In most other cases, an in-place upgrade was all that was needed.

Now that many GroupWise systems run virtualized, hardware upgrades are much less of an issue, and for the most part there is no need to migrate to a different OS. But that doesn’t mean that migrations are a thing of the past. In fact, I expect them to be with us for quite some time!

If you are using VMware, you may not be aware that the in-place upgrade of a guest OS from one major release to another is not supported.

Refer to: VMware support for guest operating system upgrade (2018695)

I haven't checked to see if similar restrictions exist with other hypervisors but I wouldn't be at all surprised to learn that there are. When you create a new VM and specify your OS, specific components are preselected that are known to be compatible with that particular OS. Even if an in-place upgrade is supported, a VM customized for a specific OS can often provide improved performance.

GroupWise documentation

The GroupWise documentation has always made it clear that GroupWise upgrades and GroupWise migrations are two different things so if you need to run a new version of GroupWise on a new server, you have to do a migration and an upgrade.

Strange as it may be, the GroupWise 18 documentation does not provide any migration documentation. It only mentions the word “Migrate” in reference to NetWare at one place in the GroupWise 18 Installation Guide and then only to refer the reader to the GroupWise 2012 Installation Guide.

The GroupWise 2014 documentation includes the GroupWise 2014 Server Migration Guide. Although not evident from its title, the focus of this document is GroupWise migrations to Linux!

The GroupWise 2014 Server Migration Guide covers many of the things you’ll want to be aware of before attempting a migration. This Cool Solution will only focus on getting your GroupWise data from point A to point B!

The Guide discusses two migration approaches, each of which has its own issues:

  1. Using the GroupWise Server Migration Utility
  2. A Manual Server Migration using DBcopy

The GroupWise Server Migration Utility documentation states that only the following GroupWise versions are supported:

  • GroupWise 2014 for Linux
  • GroupWise 2012 for Linux
  • GroupWise 8 for Linux

Most of the GroupWise migrations of which I am aware are done using DBcopy so that is what I will focus on. Many of the issues I discuss with respect to DBcopy also apply to the GroupWise Server Migration Utility. I only mention the GroupWise Server Migration Utility here so everyone knows that it is not an appropriate alternative to circumvent the issues involving DBcopy.

Manual server migration using DBcopy

A GroupWise post office can contain many (hundreds of) thousands of small files. Copying all these files can take a very long time – sometimes days! To minimise a GroupWise outage, DBcopy provides the ability to copy files from a live GroupWise system, even taking multiple passes, before shutting down GroupWise for one final copy. When copying files to a Linux system it can also force all filenames to lower case. After the copy has completed, it will invoke the gwcheck utility with the "storelowercase" option to ensure the file names in the guardian database (ngwguard.db) are also lowercase.

The GroupWise 18 Utilities Reference describes the full capabilities of both the DBcopy and the gwcheck utilities.

This is how things are supposed to work. So, what can go wrong?

Issues when following the documented migration approach

Early migrations were often from NetWare to Linux/OES. DBcopy had to be run from the destination Linux server so that it could invoke the gwcheck utility to update the guardian database with lower case names. This meant the source GroupWise file system had to be mounted on the destination server to enable the copy. This is where everything begins to fall apart.

It’s not enough to simply copy files: We want a reliable copy that has a minimum impact on the live GroupWise system!

To use DBcopy, the migration documentation instructs us to mount the GroupWise file system using NCP assuming that the source resides on NetWare or OES. It even instructs us to install the open source ncpfs package that, for a while, was distributed with SLES and OES. It fails to mention that the ncpfs package is unsupported and never was supported. Nor does it mention that NCP itself is no longer supported as of SLES11 SP2. Does it matter that it’s not supported as long as it works? Perhaps not, but in this case, customers using it encountered numerous issues which prompted SUSE to add an item to the SLES readme stating that it was unsupported. Conclusion: Don’t use NCP on SLES!

One somewhat obvious alternative is NFS. As early as GroupWise 8 there were NFS file locking issues causing corruption in a GroupWise database. This prompted a dire warning from Micro Focus to never use NFS to access an online GroupWise system! Apart from database corruption, it doesn’t even reliably copy the files.

That leaves SMB/CIFS: The Server Migration Guide provides examples of mount commands for both file systems to access data on a Windows system. As with NCP, it makes no mention of possible issues. I have asked Micro Focus to confirm whether it is safe to use SMB/CIFS to access an online GroupWise system running on NetWare or Linux but they have not provided that information. Conclusion: Use at your own discretion.

In case you were wondering, another no-no is the Novell Client for SUSE Linux Enterprise Desktop 11. I’ve tried it and it doesn’t copy reliably. While it was also supported on SLES 11 or later, Extended Support ended 31 Mar 2016.

These issues I have identified are all related to accessing an online GroupWise system remotely. To avoid these issues, the solution is simple:  don’t do it!

What are the alternatives?

If your source server is Windows or Linux, run DBcopy from the source server. On the source server, mount the volume residing on the destination server using any access method supported by the source and destination servers. Since the volume on the destination server is not being used, the issues I have identified are no longer issues.

If your source server is NetWare, run DBcopy from a Windows workstation using the Micro Focus Client for Open Enterprise Server.

If your destination server is Linux and your files have mixed case filenames, they still need to be converted to lowercase. DBcopy will still take care of this for you however, after the final copy, you will have to run gwcheck with the "storelowercase" option manually on the destination server to ensure the file names in the guardian database are also converted to lowercase.

Is there a better way?

Of course.

The techniques I am about to describe may not work for everyone. It will depend upon your specific configuration and what you need to accomplish.

One way to reduce the total migration time, and perhaps even your GroupWise outage, is not to use DBcopy at all to transfer the files.

  • Copying a large number of small files across the wire is slow because of the high overhead.
  • Coping the same files between two devices attached to the same server is much faster, especially if you use a fast, efficient, copy utility.
  • Still faster is making a clone of the whole GroupWise volume.
  • The fastest method yet involves no copying at all. Simply attach your existing GroupWise volume to your new VM!

If your domain(s) and post office(s) reside on shared storage (for example a SAN or a NAS), shut down GroupWise and do a local copy:

  • EITHER temporally attach the volume (LUN/virtual disk) containing your GroupWise data directly to the destination server
  • OR temporally attach the new volume (LUN/virtual disk) you will use on your new server to your existing GroupWise system

Once that is done you can do a local copy between the source and destination volumes using any copy utility you choose. If your server is Linux, rsync might be a good choice: it is fast and efficient. One advantage to this approach is that you can create the destination volume with a different file system should the source file system not be appropriate.

Hint: You can simplify your migrations by storing your domain(s) and post office(s) on a dedicated volume. This will be especially useful if you anticipate having to do future migrations. If you don't intend to change the file system on your GroupWise volume, all you’ll need to do is shut down GroupWise and attach the existing volume to the new server without having to copy anything at all.

If, like me, you would rather not work directly with your production GroupWise data in case something should go wrong and you would like to fall back to the existing GroupWise system quickly, use your SAN/NAS to make a LUN copy. If that is not possible, make a copy of your virtual disk using the tools provided with your hypervisor. Both these approaches are very fast, taking minutes instead of  hours or possibly days as could be the case if you were using DBcopy!

While these techniques should work for most migrations, there are always exceptions: What do you do if you have a virtual NetWare server running GroupWise, your domain(s) and post office(s) are on an NSS volume, the NSS pool uses a partition on your NetWare disk, and you want to run your new GroupWise system on Linux using a Linux file system?

If you have an OES server, that’s half the battle. Even if you don't intend to use OES, I suggest you install a trial version to simplify your migration.

  • Shut down NetWare and attach the NetWare disk to your OES VM. Better yet, clone your NetWare disk first, just to be safe.
  • Using nssmu on your OES server, mount your GroupWise volume.
  • Copy your GroupWise domain(s) and post office(s) to their own dedicated Linux volume. (2019-03-19 Update: Since you're copying files to a Linux system you must use DBcopy to force all filenames to lower case. After the copy has completed, it will invoke the gwcheck utility with the "storelowercase" option to ensure the file names in the guardian database (ngwguard.db) are also lowercase.)
  • You're done!

That's great if you have a virtual NetWare server. What do you do if you have a physical server? The concept is the same. Only the method in which you clone your NetWare disk is different!

In a previous Cool Solution, Quickly Virtualize your NetWare server, I present a method by which a NetWare disk can be cloned to virtualize the NetWare server. The same technique can be applied here.

Mmccaffe added this comment to that Cool Solution:

"In the past I have used a live linux VM as an ISCSI target and had Netware ISCSI inititator connect to the target (which presented the VM storage to Netware). Then I had Netware mirror my NSS partition to the ISCSI LUN. Once mirrored, I could shutdown the original host and present the storage to the new Nettware/Linux OES VM. This minimized down time."

I especially like this solution even though I haven't tried it myself:

  • The cloning of the NSS partition takes place while the NetWare server is doing its thing and can be setup well in advance of an anticipated migration.
  • The mirror is an exact copy of the original and is 100 percent up to date at the moment the NetWare server is shut down.
  • The copy already resides where it can be (or perhaps already is) attached to an OES VM where a local copy can be done as I described above.

Further discussions

My intent with this Cool Solution is to make you aware of some of the pitfalls that may be encountered when attempting a GroupWise migration as described in the documentation and to provide you with additional options to consider.

If you have comments, questions, or would just like to kick around a few ideas of your own, the place to do it is the Micro Focus GroupWise User Discussions forum.

I hope to see you there or maybe you would just like to have a look around on your own...


How To-Best Practice
Comment List

    Wish I saw this a few years ago when my server migration happened!  Thank you, Kevin.


    If you have comments, questions, or would just like to kick around a few ideas of your own, the place to do it is the Micro Focus GroupWise User Discussions forum.

    Please post your question in the forum where we can discuss it.

    Kevin Boyle, 
    Knowledge Partner

    Calgary, Alberta, Canada


    Years ago when I changed from gw6 to gw8; There was a cool solution that I used, I archived everyone's email.  Started a brand new server, installed gw8 on the new server, changed the user id's in console one for the users to the user id's they had on the old server, then in the clients pointed the gw clients to their respective archives (that I had copied over to the new server), and they could then pull back whatever messages/appointments they wanted.

    Can you do the same thing from gw8 to gw18?  I know console one will not be available?  

    Additional reasons for to migrate are:
    - You've kept expanding your volumes and need to consolidate the volume in a new location.
    - You are approaching some limits of the volume type such as 8TB limit of original NSS, so to migrate to NSS64
    - suboptimal initial settings on the volume such as NSS having set Salvage on at anypoint to migrate to a volume that never had it.
    - ext3 to XFS or FAT32 to NTFS
    While those may be on the same box, they aren't always, and some of this CoolSolution still applies on a same box.


    Andy of in Toronto
    Please use the "Like" and/or "Verified Answers" as appropriate as that helps us all.