Moving a GroupWise Post Office to Linux

Wikis > Caledonia Private Wiki > Moving GroupWise > Moving GroupWise to or on Linux > Moving a GroupWise Post Office to Linux

Previous Sections

For most administrators, moving the post office to a new Linux server is the most unsettling part of a move to Linux. While certainly having an MTA or GWIA or WebAccess down can be frustrating, the thought that something might “go wrong” during a post office move to Linux causes some sleepless nights.

We won’t say that there are no dangers in the move to a new Linux server, especially if it entails an OS migration as well. Frankly, any time you do something as major as changing network operating systems there are difficulties. Learning the new operating system is generally the most work for a Linux move. But getting everything “just right” is what we’re here to help you do!

You should always look at moving all but the very smallest of post offices as a two stage process. The first stage involves preparing the server and making a first pass copy of the post office data. We are often asked why we do a first pass and second pass of the copy of data from the source server to the Linux server. It’s simple: time. Unless you can afford to have your post office down for the entire time it takes to copy every file in your post office to the new server, you need to do two passes.

To explain this better, we’ll look at how DBCopy works. DBCopy is optimized to only copy files that are new or have changed since the last run of the utility. When you run DBCopy with only the parameters required to do the job, and no additional switches, DBCopy looks at each file that it is asked to copy and checks to see if there is already a file by that name in the target directory. If the file does not exist in the target directory, DBCopy copies the file. If the filename already exists in the target directory, DBCopy checks the timestamp and only copies the file if the source file is newer.

To understand this even better, we will briefly go over how GroupWise stores data. As you know, there are three data directories for a basic GroupWise post office (we aren’t counting document management directories here just yet). There is the ofuser directory, the ofmsg directory, and the offiles directory structure. When GroupWise delivers a piece of mail, a pointer is put into the ofuser directory that contains the header information for the message (sender, recipient, subject, message size, etc.). In theory then, the actual message is placed in the ofmsg database. This is true, of all message 4KB and smaller. In practice of course, with the increased use of HTML messages, these small messages are becoming fewer and fewer. Any message or attachment that is larger than 4KB is package up in a BLOB file (binary large object) and placed in the offiles directory structure. And there it sits, totally unchanged, until it is finally deleted and purged by the sender and all recipients and it can finally be removed from the system.

Thus, if you were to look at your GroupWise post office data, you would find that the vast majority (oftentimes over 90%) of the data in your post office is static information in the offiles directories. That information only needs to be copied once to your new server. And if that takes 10 hours, 20 hours, even 40 hours, you can sit back and let it happen a few days or weeks before your final move. Then on the actual “migration day” only files that have been created or modified since the first pass will need to be copied. Novell has actually also added an “incremental” switch that allows you to enter a specific date for the copy, thus even avoiding much of the checking against timestamps and file size. So, for example, if you were to make your first copy on August 30, 2009, and on September 5, 2009 you are doing the actual migration, you could put the “-i 08-30-2009” switch to prevent DBCopy from trying to copy files older than your last copy. And notice that we say “older than your last copy” here. You could technically run DBCopy multiple times prior to your final migration. For example, run DBCopy on August 30, 2009, then again on September 2, 2009, September 4, 2009, and on the 5th when it is time for the actual migration, only one day’s worth of data would need to be copied again.

Before we begin the actual migration tasks, make sure that you have accomplished all of the tasks in the chapter on “Preparing your New Linux Server”. That will have assisted you in installing the GroupWise Agents and DBCopy on your server. So now we can get down to business.

In the chapter on “Preparing your New Linux Server”, we installed the DBCopy utility that we use to migrate the data from the source server to Linux. Additionally, during the setup of your server, you installed ncpfs, which allows us to attach to a NetWare server via NCP and/or smbfs which allows us to attach to a Windows server to copy the data. If you are moving your post office from an existing Linux server, the way you mount the source server will depend on the OS you are using. If the source server is OES2 and you can access your existing GroupWise data via NCP, you can use the instructions for the NetWare mount point. If you only have Samba shares available, you can use the instructions for the Windows mount point. While it would be possible to do your Linux copy using NFS, there are so many issues with NFS in general with GroupWise that we prefer to pretend that NFS doesn’t exist. That is why we are not recommending NFS for the DBCopy portion of this migration from one Linux server to another. If you are moving from Linux to Linux, please either use NCP or CIFS.

  • Stage One – this stage can be done as many times prior to your actual migration day as you choose.
    • Create a mount point for the source server.
    • Prepare the Document Storage Locations for the Linux Server – optional for sites with External Document Storage Locations
    • Perform our first pass DBCopy of our post office.
    • Configure the POA on Linux (we won’t load it yet, but it just saves us some time on that stressful migration day!).
  • Stage Two – Migration Day
    • Unload the POA for the post office
    • Rename the post office directory to avoid any accidental access while we are relocating the post office.
    • Perform our final DBCopy pass.
    • Load ConsoleOne and edit the post office location, agent address and link information if necessary.
    • Verify that the HTTP monitor for the POA is properly enabled.
    • Load the POA for the relocated post office.
    • Log into the post office and verify that all prior data is present.
    • Send a message to a user on the same post office, and verify that it is received.
    • Verify that the POA is communicating with its domain’s MTA and force the new MTP settings through the HTTP Monitor if necessary.
    • Send a message to a user on another post office if applicable and verify that it was received
    • Send a message to an external recipient through your GWIA and verify that it was received.
    • Send a message from an external sender to your user through the GWIA and verify that it was received.

Migrating our Post Office – Stage One

Because our post office data store is large, and because we cannot afford to have our email system down for two or three days while we migrate the data, we will make an initial copy of the data while the post office is up and running. Other than some disk I/O increase, our users will not even know we are there!

Stage One can be started quite a long time before the actual migration, but there are a couple of things to keep in mind. The longer in advance you do your first DBCopy, the more “junk” you will have in your offiles directories to try to clean up later. As we noted above when we discussed how DBCopy works, the utility only copies new or newer files to the target location. However, DBCopy does no “reconciliation” of files on the servers. In other words, if you do a first pass copy of your post office on September 1, 2009, and then don’t do your actual migration until September 30, 2009, anything in the offiles structure that has been deleted from the live post office in the meantime will still exist on the Linux server. It would be unwise, therefore, to do a first pass copy before instructing users to clean our their mailboxes and purge their trash! In that case, you would have cleaner databases, but you would still have old files in the offiles directories. And we all know (at least those of us who have been around for any time at all know!) how difficult it is to get rid of old orphaned files in the offiles directories. Thus, it is best to try to have your users clean up before you do your first pass with DBCopy.

Once you have your server prepared and ready for your migration, and you are within your reasonable “migration window” for starting your first pass DBCopy run, it’s time to get down to business.

Create a Mount Point for the NetWare or OES2 Server Using NCPFS

If you are moving your post office from NetWare or OES2, you need to attach to the source server from your new Linux server. To mount the NCP volumes into your Linux file system, perform the following steps:

  1. On the Linux server, open up a terminal window.
  2. “su root” to become root for this session.
  3. Create a directory structure for your mount point. For our purposes, we have created /mnt/gw1 as the mount point for our NetWare or OES2 server that is named gw1. It is suggested that you replace gw1 with the actual name of your source server for ease of recognition later.
  4. We have chosen to connect to our NetWare server via ncpfs. To mount the NetWare server via ncpfs, issue the following command

 

ncpmount -S server -A 123.123.123.123 -U userid -P password /mnt/gw1

replacing your server name for “server” and your server’s IP address for 123.123.123.123. For example

ncpmount -S gw1 -A 192.168.100.200 -U danita.cnc -P password /mnt/gw1

 

NOTE: You might wonder about the “user.context” vs. “.user.context” in this example. While “.user.context” works on some versions of Linux, it fails on others. In my testing, “user.context” has always worked on all versions. You might keep this in mind if you experience any problems authenticating with ncpmount.

 

This will actually mount all volumes from the NetWare server to this location. So, if we cd to /mnt/gw1 will will see a directory called SYS, one called GWDATA, one called GWDOCS and any other volumes that are on that server.

Create a Mount Point for the Windows or Linux Server using CIFS

If you are moving your post office from Windows or a Linux server with CIFS, you need to attach to the source server from your new Linux server. To mount the source server’s drives into your Linux file system, perform the following steps:

  1. On the Linux server, open up a terminal window.
  2. ”su root” to become root for this session.
  3. Create a directory structure for your mount point. For our purposes, we have created /mnt/gw1 as the mount point for our source server that is named gw1. It is suggested that you replace gw1 with the actual name of your Windows server for ease of recognition later.
  4. We have chosen to connect to our Windows or Linux server via cifs. To mount the source server via cifs, issue the following command:

 

mount -t cifs //server/d$ /mnt/name -o username=user,password=password, domain=domain or workgroup

 

This command is all one line, and there is no space between the comma following password and the word domain. You can use the entire drive (d$) or a specific share name. We like to use the drive (d$) when possible, but the share works as well, and must be used for a Linux server. If for some reason you have difficulty mounting by by server name, you can substitute the IP address of the source server in the //server/d$ portion (i.e. //192.168.100.201/d$).

So, for example, our command would be

mount -t cifs //192.168.100.228/d$ /mnt/gw1 -o username=danita,password=pass,domain=caledonia

 

Preparing Document Storage Locations for the Linux Server

If you use GroupWise Document Management on Windows or NetWare, and have external Document Storage Locations defined, these must be moved separately from the main post office migration. Because there is a special entry for the Storage Location for Linux, you will not be able to load your POA on Linux until this field has propogated properly to the wphost.db file. After much experimentation, we have found the best way to do this, and it is is not always obvious. If you following these steps, you will find that the migration of your storage locations will be stress-free!

If you use GroupWise Document Management and have external document storage locations, then we will need to do a few things differently. First, we will do some initial preparation of the storage locations. After we verify the success of this first step, you will continue on with the migration of the post office. And finally, after the post office is successfully moved, and users can log into the post office, we will complete the move of the External Storage Locations. If your External Storage Location is on the same server as your Post Office, then we mounted that drive into our Linux file system immediately prior to this step. If for some reason your External Storage Location is on a separate server, you would need to follow the steps for creating the mount point again, this time mounting the server for the External Storage Location.

Change the Case of your Post Office and Storage Areas

First, at a minimum the following needs to be all lowercase before we continue:

  • wphost.db
  • ngwguard.db
  • gwdms directory structure
  • external storage area directory names

While those are the only files/directories that really must be lowercase, in order to make for a smooth migration of the External Storage areas, we recommend that you just Google for Change Case or ftweak-case and run it against your entire post office directory structure and your document storage locations.

Connect to the Post Office’s Owning Domain in ConsoleOne

Connect to the domain that owns this post office in ConsoleOne. This can be ConsoleOne on Windows, or Linux.

Verify that the Post Office is Set to Verbose Logging

If you keep your Post Office Agent on verbose logging, you will not need to change anything. Otherwise, at the Post Office Agent Console, choose Options|Logging Options and set to verbose.

Edit the Information in ConsoleOne for the Storage Location

 

  • In ConsoleOne, select the Library involved in the storage move.
  • Right click and select Properties.
  • Select the Storage Area page of the Library.
  • Select the Storage Area that you will move.
    1. Click the Edit button. You will see the screen in Figure 8-1.
      1. FigureP-x.tiffEdit Document Storage Area

 

  • We need to set the Linux Path. In our example, our External Storage Location is on a server called gw1, on a volume called GWDOCS, in the \library\burns directory structure. Since we have mounted our gw1 server in /mnt/gw1, our Linux path to this existing location is /mnt/gw1/GWDOCS/library/burns. Click OK. You will notice that in the “Storage Area” window there is no “OK” button available. You can just click Cancel here. (If you are skeptical, you can edit the storage location again to verify that your change has been made.)
  • Next go and watch the POA log until you see the entry that shows that the Storage Area has been updated.
  • Now, unload the POA on your source server. For example, on NetWare, press F7 to unload the POA. Of course, this will need to be done at a time when you can schedule a short downtime window for the post office.
  • We will now load the POA from the Linux server, pointing to our post office on our source server. In our case, our source location is now mounted at /mnt/gw1/GWDATA/pos/cal2. We will thus load our POA with the following command:

/opt/novell/groupwise/agents/bin/gwpoa –show –home /mnt/gw1/GWDATA/pos/cal2

If all goes according to plan, your POA will load normally. However, if you receive a C06B error, the POA will simply shut down. If this happens, you need to load the POA back on your source server, and repeat the steps starting with “Verify that the Post Office is Set to Verbose Logging” until you can successfully load the Linux POA against your source post office database.

  1. Once you successfully load the Linux database against the source post office database, shut down the Linux POA and reload the source POA. We will come back to the External Storage Area after the Post Office has been migrated.

 

Performing Our First Pass DBCopy of the Post Office.

Decide where you wish to have your post office located on your server (local partition, SAN, etc.) and make sure that your location is ready to receive your data. It is not necessary to have actually created the post office directory on this partition, as the DBCopy utility will create it for you.

In our example, our NetWare volume is mounted at /mnt/gw1/GWDATA/pos/caledoni. Our new location for our data will be in /grpwise/pos/caledoni.

The absolutely most important thing to remember when performing your DBCopy from NetWare or Windows to Linux is the -m switch. This is the “migrate” switch, and it changes the case for all of the data to lowercase. We can’t stress enough how critical this is. We have been involved in migrations where this switch was forgotten. Especially if you plan on doing more than one “first pass” you must be extremely careful. There is nothing more frustrating than having a DBCopy run for 20 hours the first time, all files dutifully converted to lowercase, and then come back for another pass, forgetting the -m switch, and having duplicates of all file names in two different cases! In fact, some of our customers have been so wary of this, that they simply run the Change Case utility that we discussed back in our preparation chapter prior to beginning their migration first pass just to lessen the damage that would be incurred by forgetting the -m switch!

If you have an older version of GroupWise, and your ngwguard.db file on the NetWare server is not all lowercase, it is advisable to change that prior to starting the DBCopy. You must take down your POA in order to change the case for this file of course. While newer versions of DBCopy should do okay with an uppercase ngwguard.db file, we have seen issues with the -m switch failing, and it’s just better to be safe than sorry!

So, getting down to business, here’s how we will copy our data.

 

You will find that DBCopy on the Linux server does not run well from any directory other than /opt/novell/groupwise/agents/bin so we will cd to that location to run the utility. Run DBCopy to copy your files from the source server to the Linux location like this:

./dbcopy -m -p <source> <destination>

so for our situation it would be

./dbcopy -m -p /mnt/gw1/GWDATA/pos/caledoni /grpwise/pos/caledoni

This will copy all needed data from the current post office directory into the directory structure that we have indicated for the destination. In our case, we have chosen to location our post office in /grpwise/pos/caledoni. Our post office is named “Caledonia”. While in theory we should be able to have a post office directory of more than 8 characters on Linux, we do not do this for compatibility and consistency sake.

The -m switch copies the files over in all lower case. The -p switch tells DBCopy that it is migrating a post office. If you are extremely curious and just love watching screens fly by to prove that something is happening (don’t be shy – Danita is just like that herself!), you can also include the -w switch. This writes all of the data to the “window” so that you can see each file as it is copied. If you DO enable this switch though, do not expect to be able to really tell where you are in the copy. DBCopy launches multiple threads (by default 5) to do the copying, and does not seem to always follow any particular order in the directory structure.

Go get a cup of coffee. Or dinner. Or watch a movie. Or just go home for the weekend! This can take a long time, and there is almost no way to calculate it for you. The time it takes you to do current backups of your full post office is a start at an estimation. The faster the connection between your new Linux server and the source server the better. And of course, if you are migrating from an ncp server, ncp isn’t necessarily the fastest of protocols out there, but it requires no special configuration on your NetWare server, and is Novell’s recommended way to copy the data from NetWare to Linux. While on some versions of NetWare you could serve up the post office via CIFS, it probably isn’t worth the effort to try to configure this solely for the purpose of this migration. And under no circumstances should you attempt to do any type of NFS mount to your source server. For the vast majority of sites, you will find it easier and safer to just follow the instructions outlined here for using ncpfs for NetWare or cifs for Windows and having the data copy over via DBCopy that way.

Configure the POA on Linux

After the first run of DBCopy, it is advisable to go ahead and configure your POA so that it will be ready to load on migration day. Novell’s migration utility actually even loads the POA on the Linux server and suggests that you log into the POA on that server to see that your data looks okay. We will walk through those steps manually as well, so that you can verify that the first copy looks okay.

The configuration process will create a new startup file for the POA, and configure the agent to launch upon startup.

In a terminal window, go back to the location where you extracted your GroupWise distribution above in Preparing Your Server. Run the install script as root. For example:

 

gwlinux:/grpwise # ./install

 

  1. Choose Install Products.
  2. Choose GroupWise Agents.
  3. Choose Configure Agents.
  4. At the License Agreement screen, accept the license.
  5. The next screen will look very familiar to GroupWise administrators (see Figure 8-2). This is where we list the agents that will run on this server to create startup files and the startup script for Linux.

 

    1. Figurel-d7.tiffGroupWise Agents Configuration

 

 

  1. Enter the information for your post office, using the local Linux path (see Figure 8-3)

 

    1. Figurel-p1.tiffPost Office Information

 

  • After your post office information is entered, click next to move on to the startup screen.
  • You will be asked if you wish for your agent to load on startup. This box is already checked, but really just looks like a red box. You will notice that if you click on the box, it becomes white (unchecked) and clicking again will recheck the box. It is advisable to have your agents load on startup.
  • Click Exit to leave this setup, and then click the Exit icon (at the bottom right of the screen) to leave the GroupWise installation program.

 

When you perform these tasks, a startup file is created for the post office’s POA, and if you chose to launch on startup, symbolic links were created in the proper run level directories to start the agent automatically. Looking at the /opt/novell/groupwise/agents directory you will see directories named bin, lib and share. Under bin you will see the agent executables, as well as default startup templates. Under the share directory are a couple of directories, and the caledoni.poa startup file that was created by our installation. Let’s run this agent now and see what it looks like.

Starting the GroupWise POA with the GUI for Testing

The first time we start a new agent on a Linux server, we like to start it with a GUI console to test that everything is working properly. It’s important to know that you will not run your agents with the GUI console as standard practice. We will load our POA up for the first time with the GUI console solely to verify that there are no problems with our installation.

The easiest way to start the GUI agent is as follows:

From a terminal window, change to the /opt/novell/groupwise/agents/bin directory. From here, type the following:

./gwmta –show @caledoni.poa &

This should bring up the agent screen as shown in Figure 8-4.

    1. Figurel-p2.tiffThe GroupWise Post Office Agent

 

You can log into this POA by pointing to it directly via IP address by running GroupWise with the /@u-? switch. This will open GroupWise with a dialog box that allows you to enter the pertinent information. For example:

  1. Figurel-p3.tiffThe GroupWise Startup Screen

Then you can see whether or not the mail looks the same as on the live server at the time of the copy.

  1. Figurel-p4.tiffLogged in to the copied post office

 

Once you are satisfied that your initial copy was successful and that you can access your post office with the new startup switch, exit GroupWise and close the POA.

It is best to try to avoid restarting this server between now and migration day. It would not be a critical problem, except of course that we have configured the server at this point to automatically load the POA on startup. This should not pose any great problems if it were to load unattended, but it would be best to not have to worry about the POA running when it comes time to do our final copy.

As mentioned earlier, you can do a “first run” copy any time you choose between now and the final migration day. It’s usually not that important to do though, unless you want to incrementally reduce the amount of time the copy takes on the final day.

Migrating our Post Office to Linux – Migration Day

Today’s the day, and we will complete our migration of the post office to Linux. Users have been alerted that the email system will be unavailable for the duration, and we are ready to proceed.Here are the tasks that we will complete in order to accomplish our migration:

  • Unload the source server POA for the post office
  • Rename the domain post office directory to avoid any accidental access while we are relocating the post office.
  • Perform our final DBCopy pass.
  • Load ConsoleOne and edit the post office location, agent address and link information if necessary.
  • Verify that the HTTP monitor for the POA is properly enabled.
  • Load the POA for the relocated post office.
  • Change the ngwnameserver entries in our local DNS if applicable
  • Log into the post office and verify that all prior data is present.
  • Send a message to a user on the same post office, and verify that it is received.
  • Verify that the POA is communicating with its domain’s MTA and force the new MTP settings through the HTTP Monitor if necessary.
  • Send a message to a user on another post office if applicable and verify that it was received
  • Send a message to an external recipient through your GWIA and verify that it was received.
  • Send a message from an external sender to your user through the GWIA and verify that it was received.

 

It seems like a lot of work, but some of it can be done while the post office is doing its final copy.

 

Unload the POA

First of all, go to the source server where your POA is loaded for the domain that you are moving:

  • NetWare: press F7 at the agent console to unload the agent
  • Windows: if the agent is running as an Application, you can also press F7, or use the File Menu and Exit. If the agent is running as a Service, you must stop the agent from the services applet.
  • Linux: use rcgrpwise command. For example:

rcgrpwise stop POName.DomainName

If you are not certain of the name that is defined for your post office in the rcgrpwise script, first run:

rcgrpwise status

This will show you all agents that the rcgrpwise script controls. Find the name for your POA and then issue the stop command for your POA.

At this point we will also make sure that the POA that we configured above on our destination server did not get left loaded, or in the case of a server reboot, get loaded again before we continue.

In a terminal window on the destination Linux server, type:

rcgrpwise status

  • You should see something like this:

Checking status [Caledonia.CNC] unused

If “unused” is replaced with “running” issue this command

rcgrpwise stop Caledonia.CNC

Of course, Caledonia is the name of our post office, and CNC is the name of our domain. You should use the name that is listed in your “checking status” command for your post office.

Just to be safe, now issue this command in the terminal window:

ps -A | grep gwpoa

This should just return you to a terminal prompt indicating that no instances of gwpoa are running. If you see something like this:

9980 pts/3 00:45:23 gwpoa

you will need to kill the process. First try a command like this

kill 9980

notice that 9980 was our process number in the above list. Substitute the number for your gwpoa process here. Try the ps -A | grep gwpoa again. If this still persists, try this:

killall gwpoa

Once your gwpoa process is finally no longer listed, continue on.

 

Rename the post office directory

Just to be safe, we always rename the post office directory on the source server to ensure that no one (or no utility) can access the post office while we are making our final copy.

Perform our final DBCopy pass.

Our final DBCopy pass will be very similar to the first. The big differences here are that we will use the -i switch to limit what work DBCopy must do, and we will alter the source directory to reflect that we have renamed our post office directory.

You will find that DBCopy does not run well on the Linux server from any directory other than /opt/novell/groupwise/agents/bin so we will cd to that location on the destination server to run the utility. Run DBCopy to copy your files from the source server to the destination Linux server location like this:

./dbcopy -m -p -i mm-dd-yyyy <source> <destination>

so let’s assume that we did our last DBCopy to the Linux server on September 3, 2009. Our command would be

./dbcopy -m -p -i 09-02-2009 /mnt/gw1/GWDATA/pos/caledoni.old /grpwise/pos/caledoni

We always make the -i switch the day before our last copy just to be safe!

Again, this will take some time. It’s difficult to say how long exactly. However, in a recent migration we did, the initial DBCopy of all of the post office files took about 20 hours, and the final DBCopy took two hours.

While this is processing we can continue to do a bit of work that needs completing.

Additional Migration Tasks to Do While the Final Copy Continues

There are a few steps that need to be accomplished before we are finished with our migration.

Edit the Details of the Post Office in ConsoleOne

Load ConsoleOne and if possible connect to the domain that owns this post office. While the changes could be done from any domain location, being connected to the domain that owns the post office aids in getting the changes propagated more efficiently.

  • Edit the properties of the post office and change the UNC path of the post office to point to the new location.
  • Edit the properties of the POA object, and change the following:
    • On the Identification screen, change the Platform to Linux
    • On the Agent Settings screen (click the triangle on the GroupWise tab to change to this screen), notice the HTTP Monitor settings. If you have never enabled the HTTP monitors for your agents, you will need to decide on a good userid and password for the HTTP monitors. Please note that this is neither an eDirectory user nor a GroupWise user. This is an entirely made up user and password solely for the use of the HTTP monitors. If all administrators in your organization will have rights to use the HTTP monitors, then it is a good idea to have the same userid and password for all agents. If you need to limit rights to some agents to various groups, set up a userid and password for each group of agents that will be monitored. Enter the userid and password that you have decided on here in this screen.
    • On the Network Address screen, change the IP address of your POA to reflect the IP address of the new server. Make sure that a valid port number is listed in the HTTP Monitor field, and note what that port is.
    • On the Log Settings tab, remove any custom log locations and leave the logging to the default location
    • Click OK to save all of the changes.

 

NGWNameserver

If your site is using an ngwnameserver value in DNS to direct users to the POA, you should change this now to point to the new IP address for your POA. This will ensure that users have no disruption of service after the POA comes back up. The DNS server will simply redirect the users to the proper IP address after the migration.

 

And now we wait. There really isn’t much left to do until the copy is complete!

Additional Migration Tasks to Do After the Final Copy is Complete

StoreLowerCase

If all goes well with your DBCopy, a gwcheck with a “storelowercase” option will be issued by the utility at the very end. This tells the ngwguard.db that all files in the GroupWise system are now lowercase. The only time you should ever have to run a gwcheck with a “storelowercase” option yourself if if you do not use DBCopy with an -m and -p switch. We bring this up, because there are still some TIDs floating about that recommend that you DO run a “storelowercase”. And while there are instances where you indeed might need to do this manually, it CANNOT BE STRESSED ENOUGH that you should NEVER run a gwcheck with a “storelowercase” while the POA is loaded. Unfortunately, ConsoleOne will actually allow you to request such a thing through Mailbox/Library Maintenance, which of course will have the POA run the gwcheck itself. This can cause no end of suffering. Please do not do this.

Loading the POA

Once the copy has completed, it’s time to load up the POA and see if everything is working. We verified earlier that the POA loads properly by manually loading it, so this time we will let the rcgrpwise script handle the job.

Earlier we did an rcgrpwise status to verify that our POA was not running. At that point we saw that the rcgrpwise script has identified our post office as Caledonia.CNC. Your post office should simply be identified as PO.Domain. In order to quickly load this, we can go to a terminal window and type:

rcgrpwise start Caledonia.CNC

You should see something like this:

Starting done

A quick

rcgrpwise status

should now show

Checking status [Caledonia.CNC] running

 

Checking the MTP Link

Frequently when moving a post office, the message transfer link between the MTA and the POA is broken. For those of you who have never used the HTTP monitors for the agents before, this will be a really good example of “learning to love the HTTP monitor”. Because even though it’s something you have to get used to doing since we are not loading the GUI Consoles for our agents (except in testing situations), the solution that we will show now is not available in any of the GUI Consoles! So the HTTP monitor wins our love and devotion in one simple command.

The first thing we are going to do is log into our POA’s HTTP monitor. Using your favorite browser (we prefer Firefox, but Internet Explorer works as well), go to the IP address and port of your POA’s HTTP monitor. Our location is http://192.168.100.169:7181 – and unless you changed the default port for your POA, you will also go to 7181. When we enter this address, we are first asked for a userid and password. This is the userid and password we assigned to the HTTP monitor in “Edit the Details of the Post Office in ConsoleOne” above.

After authenticating, we are presented with the following screen:

  1. Figurel-p5.tiffThe POA HTTP Monitor

At this point we want to click on the link for MTP Status, and we will see this screen:

  1. The POA MTP Status ScreenFigurel-p6.tiff

 

You will notice that the Receive Status shows as Closed, and that the Inbound TCP/IP address shows our old IP address. This is due to the simple fact that our POA doesn’t know that it has moved! This is easily rectified. Simply click on the Closed link under the word Received, change the IP address to the current IP address of the POA on Linux, click the Start MTP Receive radio button, and click Submit. Now click the MTP Status link again and you will see that the Receive thread shows Open. Your MTA and POA are talking to each other again, and mail can begin flowing.

Log into the POA on the Linux Server

It’s now time to log into your new POA and verify that everything is working as desired. If you use the ngwnameserver listing as described above, your GroupWise client will initially try to go to the old server, timeout and then ask for the new entry in DNS. If you do not use ngwnameserver, you will likely need to enter the new IP address manually when the login times out.

Once you have logged into your mailbox, there are a few tasks that you should perform to ensure that everything is working properly

  • Send a message to yourself. This should pop into your mailbox almost immediately.
  • Send a message to a user on the same post office, and verify that it is received.
  • Send a message to a user on another post office if applicable and verify that it was received
  • Send a message to an external recipient through your GWIA and verify that it was received.
  • Send a message from an external sender to your user through the GWIA and verify that it was received.
  • If you use GroupWise Document Management and your documents are all stored under the Post Office directory structure, open an existing document and verify that you are able to access it properly.
  • Create a new document in GroupWise DMS and verify that it creates and saves properly.

 

Once all of these tasks are performed successfully, you are DONE. Unless of course you need to move an External Storage Area. In that case, continue on with the next section.

 

Moving External Document Storage Locations

After completing the above settings for our External Storage Areas, our users are now accessing their documents on the source server. While this works for now, Novell does not support this configuration long-term, and we need to get the documents moved over as soon as we can.

First, decide where on your Linux server you wish to have the Document Storage Location. It is not recommended on Linux that this be on a server separate from the post office. While this has worked in the past for Windows and NetWare, it is not a supported operation for your Linux POA to log into another server to access documents.

Once you have decided on your location, we will do a new DBCopy. This time we will use the -m switch again, but also a new switch called -b (BLOB), which essentially tells the DBCopy utility to not check the ngwguard.db file while it is running and simply copies everything it finds in the source directories.

First we will unload our Linux POA just to avoid issues. Follow the instructions above in “Unload the POA” to ensure that the POA is not loaded. We will also make a copy of the wphost.db file and place it somewhere safe. If after you change the storage location you run into any problems, you can put the copied wphost.db file back while you regroup and try again.

We assume that you still have your source server for your document storage location mounted in the /mnt structure. If you do not, please go to “Create a Mount Point for the NetWare or OES2 Server Using NCPFS” or “Create a Mount Point for the Windows or Linux Server using CIFS” and follow those steps again to mount your source server volumes.

With the source volumes mounted, we will begin our copy. In our situation, the documents are on our gw1 server, in a volume called GWDOCS in a directory called \library\burns. Our documents will reside on a separate Linux partition on our server that is mounted at /grpwise/library/burns. Thus, our DBCopy command would look like this:

./dbcopy -m -b /mnt/gw1/GWDOCS/library/burns /grpwise/library/burns

Once our documents have been copied over to our Linux partition, we will load ConsoleOne and do some magic.

  1. In ConsoleOne, select the Library involved in the storage move.
  2. Right click and select Properties.
  3. Select the Storage Area page of the Library.
  4. Select the Storage Area that you have moved.
  5. Click the Edit button.
  6. Change the UNC path on the Edit the Document Storage Area page.
  7. Change the Linux Path on the Edit the Document Storage Area page.
  8. Select OK.
  9. Select Apply.
  10. Select OK, to close the Library Properties window.
  11. Verify the change took effect. Close ConsoleOne, then load ConsoleOne again and view the properties of the Library and its Storage Area.
  12. Load the POA manually, with the following switches:
    • –ll verbose- logging switch which sets the log level to verbose to enable you to better track the configuration changes (if your POA is already set to verbose logging, you can skip this switch)
    • –noconfig – this switch will prevent the POA from reading its own configuration file. Instead it will load with “defaults” and simply receive information from the MTA about the change.

This command will look like this:

/opt/novell/groupwise/agents/bin/gwpoa –show –home /grpwise/pos/cal2 –ll verbose –noconfig

 

  1. Let the POA run like this for a few minutes until you see that the configuration settings have propagated.
  2. Unload the POA and reload it with its regular startup file.
  3. Test the new storage area by opening a document in the library. Close the document, and look at the activity log for the document. To view the activity log go the Properties of the document, select the Activity Log tab. From here you can see the Filename column which will display the exact path to where the document is stored in your GroupWise library. If you do not see the Filename column, simply right click on the column heading and click the word Filename when it appears. This will add this column to the view. You should now see that the document is showing located in the new volume.
  4. Finally, create a new document in the library, then view its activity log to verify it was saved into the new storage area.

 

If you run into any difficulties during this switch of the document storage locations, put back the wphost.db file that you copied before we began. You can try again later if necessary.

 

Moving a GroupWise Post Office to a new Linux Partition

If your GroupWise data already resides on a Linux server, you may need to move it for a number of reasons:

  • You decide to change the file system. Let’s say that your current GroupWise data is on a ReiserFS partition, and you wish to move it to NSS. There is no way to just “convert” that partition, so you would need to move the data.
  • You have a large /var partition and your GroupWise post office started out there. You wish to segregate your GroupWise data from other data onto its own partition.
  • You have run out of space on your current partition. With current technology, this is becoming less and less likely of a scenario, but there are still some situations where this would be the case.

In any of these situations, the “moving” of the data is not much of a problem. It’s the “time” involved that becomes difficult. Because of the sheer size of the typcial GroupWise post office, we will need to approach this much the same as a server migration. So, we will follow a similar path.

The steps we will take are as follows:

  • Stage One – Stage “One” can be done as many times prior to your actual cut over day as you choose.
    • Perform our first pass DBCopy of our post office.
  • Stage Two – Moving Day
    • Unload the POA for the post office
    • Rename the post office directory to avoid any accidental access while we are relocating the post office.
    • Perform our final DBCopy pass.
    • Load ConsoleOne and edit the post office location if necessary.
    • Load the POA.
    • Log into the post office and verify that all prior data is present.
    • Send a message to a user on the same post office, and verify that it is received.
    • Verify that the POA is communicating with its domain’s MTA.
    • Send a message to a user on another post office if applicable and verify that it was received
    • Send a message to an external recipient through your GWIA and verify that it was received.
    • Send a message from an external sender to your user through the GWIA and verify that it was received.

 

Moving our Post Office to a New Partition – Stage One

Because our post office data store is large, and because we cannot afford to have our email system down for two or three days while we copy the data, we will make an initial copy of the data while the post office is up and running. Other than some disk I/O increase, our users will not even know we are there!

Stage One can be started quite a long time before the actual move, but there are a couple of things to keep in mind. The longer in advance you do your first DBCopy, the more “junk” you will have in your offiles directories to try to clean up later. As we noted above when we discussed how DBCopy works, the utility only copies new or newer files to the target location. However, DBCopy does no “reconciliation” of files on the servers. In other words, if you do a first pass copy of your post office on September 1, 2009, and then don’t do your actual move until September 30, 2009, anything in the offiles structure that has been deleted from the live post office in the meantime will still exist on the new partition. It would be unwise, therefore, to do a first pass copy before instructing users to clean our their mailboxes and purge their trash! In that case, you would have cleaner databases, but you would still have old files in the offiles directories. And we all know (at least those of us who have been around for any time at all do!) how difficult it is to get rid of old orphaned files in the offiles directories. Thus, it is best to try to have your users clean up before you do your first pass with DBCopy.

Once you have your new partition prepared and ready for your move, and you are within your reasonable “move window” for starting your first pass DBCopy run, it’s time to get down to business.

Performing Our First Pass DBCopy of the Post Office.

For the sake of this discussion, our data currently resides in the /var directory structure in /var/opt/novell/groupwise/pos/caledoni. We have created a new partition and mounted it as /grpwise. Thus, we will now put our post office at /grpwise/pos/caledoni. There is no need (and no desire at this point) to take down the post office agent. Users will still be able to access GroupWise, and mail will flow in and out of the system during this copy procedure.

You will find that DBCopy on the Linux server does not run well from any directory other than /opt/novell/groupwise/agents/bin so we will cd to that location to run the utility. Run DBCopy to copy your files from the source server to the Linux location like this:

./dbcopy -p <source> <destination>

so for our situation it would be

./dbcopy -p /var/opt/novell/groupwise/caledoni /grpwise/pos/caledoni

This will copy all needed data from the current post office directory into the directory structure that we have indicated for the destination. In our case, we have chosen to location our post office in /grpwise/pos/caledoni. Our post office is named “Caledonia”. While in theory we should be able to have a post office directory of more than 8 characters on Linux, we do not do this for compatibility and consistency sake.

The -p switch tells DBCopy that it is migrating a post office (and really is optional). If you are extremely curious and just love watching screens fly by to prove that something is happening (don’t be shy – Danita is just like that herself!), you can also include the -w switch. This writes all of the data to the “window” so that you can see each file as it is copied. If you DO enable this switch though, do not expect to be able to really tell where you are in the copy. DBCopy launches multiple threads (by default 5) to do the copying, and does not seem to always follow any particular order in the directory structure.

Go get a cup of coffee. Or dinner. Or watch a movie. Or just go home for the weekend! This can take a long time, and there is almost no way to calculate it for you. The time it takes you to do current backups of your full post office is a start at an estimation.

As mentioned earlier, you can do another “first run” copy any time you choose between now and the final move day. It’s usually not that important to do though, unless you want to incrementally reduce the amount of time the copy takes on the final day.

Moving our Post Office to a New Partition – Stage Two

Today’s the day, and we will complete our move of the post office to Linux. Users have been alerted that the email system will be unavailable for the duration, and we are ready proceed.

Here are the tasks that we will complete in order to accomplish our migration:

  • Unload the POA for the post office
  • Rename the domain post office directory to avoid any accidental access while we are relocating the post office.
  • Perform our final DBCopy pass.
  • Load ConsoleOne and edit the post office location, if necessary.
  • Reload the POA for the relocated post office.
  • Log into the post office and verify that all prior data is present.
  • Send a message to a user on the same post office, and verify that it is received.
  • Verify that the POA is communicating with its domain’s MTA.
  • Send a message to a user on another post office if applicable and verify that it was received
  • Send a message to an external recipient through your GWIA and verify that it was received.
  • Send a message from an external sender to your user through the GWIA and verify that it was received.

 

Unload the POA

Stop your post office agent with the rcgrpwise command. Typically you would type:

rcgrpwise stop POName.DomainName

If you are not certain of the name that is defined for your post office in the rcgrpwise script, first run:

rcgrpwise status

This will show you all agents that the rcgrpwise script controls. Find the name for your POA and then issue the stop command for your POA.

 

Rename the post office directory

Just to be safe, we always rename the post office directory on the source partition to ensure that no one (or no utility) can access the post office while we are making our final copy.

Perform our final DBCopy pass.

Our final DBCopy pass will be very similar to the first. The big differences here are that we will use the -i switch to limit what work dbcopy must do, and we will alter the source directory to reflect that we have renamed our post office directory.

You will find that dbcopy does not run well on the Linux server from any directory other than /opt/novell/groupwise/agents/bin so we will cd to that location on the destination server to run the utility. Run dbcopy to copy your files from the source server to the destination Linux server location like this:

./dbcopy -p -i mm-dd-yyyy <source> <destination>

so let’s assume that we did our last dbcopy to the Linux server on September 3, 2009. Our command would be

./dbcopy -p -i 09-02-2009 /var/opt/novell/groupwise/pos/caledoni.old /grpwise/pos/caledoni

We always make the -i switch the day before our last copy just to be safe!

Again, this will take some time. It’s difficult to say how long exactly. However, in a recent migration we did, the initial DBCopy of all of the post office files took about 20 hours, and the final DBCopy took two hours.

Once the copy has completed, you can continue.

Edit the Details of the Post Office in ConsoleOne

If your file system location is going to change, you will need to edit the post office location in ConsoleOne. Remember though, this is Linux. And even though our post office was on /var/opt/novell/groupwise/pos/caledoni before, and we’re moving it to /grpwise/pos/caledoni, this does not mean that the location has to actually “change” from the perspective of the POA. We can simply mount the partition that we are currently calling /grpwise back as /var/opt/novell/groupwise/ if we choose. This means that nothing must change in ConsoleOne and not even the startup file needs to be edited before we reload the POA!

That of course is the way we would recommend it be done. However, if you do need to change the logical path on the server, then do the following:

  • Load ConsoleOne and if possible connect to the domain that owns this post office. While the changes could be done from any domain location, being connected to the domain that owns the post office aids in getting the changes propagated more efficiently.
  • Edit the properties of the post office and change the path of the post office to point to the new location.
  • Edit the startup file for your post office that is in /opt/novell/groupwise/share and change the –home switch

 

Loading the POA

Once the copy has completed, it’s time to load up the POA and see if everything is working. Your post office should simply be identified for your script as PO.Domain. In order to quickly load this, we can go to a terminal window and type:

rcgrpwise start Caledonia.CNC

You should see something like this:

Starting done

A quick

rcgrpwise status

should now show

Checking status [Caledonia.CNC] running

 

Log into the POA to Check on the Move

It’s now time to log into your POA and verify that everything is working as desired.

Once you have logged into your mailbox, there are a few tasks that you should perform to ensure that everything is working properly

  • Send a message to yourself. This should pop into your mailbox almost immediately.
  • Send a message to a user on the same post office, and verify that it is received.
  • Send a message to a user on another post office if applicable and verify that it was received
  • Send a message to an external recipient through your GWIA and verify that it was received.
  • Send a message from an external sender to your user through the GWIA and verify that it was received.
  • If you use GroupWise Document Management, open an existing document and verify that you are able to access it properly.
  • Create a new document in GroupWise DMS and verify that it creates and saves properly.

 

Once all of these tasks are performed successfully, you are DONE.

Next Section