Revision for “Upgrading Your Secondary Domains” created on December 9, 2013 @ 23:32:51
Upgrading Your Secondary Domains
The only real prerequisite to upgrading a secondary domain to GroupWise 2012 is that the primary for the GroupWise system must first be upgraded. As we discussed in Chapter 3, after the primary domain is upgraded, it sends an administrative message to all of the secondary domains in the system that the primary is now GroupWise 2012. Once this has occurred, then the secondary is available to be upgraded. Loading a GroupWise 2012 MTA against a domain is not enough to upgrade the domain. It has to have permission before the domain can upgrade.
How Does the Upgrade Work?
At the domain level, a GroupWise upgrade is really just a database conversion from one version to another. The former GroupWise domain database (all GroupWise versions 5.0 through 8.0 work the same), is RECOVERED by the MTA’s administrative thread and CONVERTED to the new version. For a Secondary Domain, this requires two simple components:
Just as the primary domain sends a message to its secondaries that it is now GroupWise version 12, secondary domains send out a message to all of their post offices to alert them to the fact that their owning domain is now a GroupWise 2012 domain. This is very important later when we move to other post offices in this domain. Unless this message is properly delivered (POAs are down, for example), the post offices will not upgrade, even though they may be running the GroupWise 2012 software for their agents. We’ll discuss this more as we walk through this upgrade.
Getting Ready for the Upgrade
In Chapter 3, we created what we termed our “Master SDD”. This has all of the software needed for a GroupWise installation, and you should have a copy of this available to you when you upgrade your secondary. This may mean that you simply attach to this software in the same place it was created for the upgrade of the primary domain. However, if this is over a WAN link you might prefer to have the SDD available locally.
As mentioned in Preparing for Your GroupWise Upgrade, GroupWise 2012 requires ConsoleOne® 1.3.6h or later. This is included on the GroupWise 2012 media. This also requires Java Virtual Machine (JVM) 1.5.11 or later, which is installed along with ConsoleOne. It is very important that you upgrade ConsoleOne to this version. The GroupWise 2012 snapins will not function with older versions of ConsoleOne. It is possible that you are managing your secondary domain from the same administration workstation as you used for your primary domain. If this is the case, and if your secondary domain is in the same eDirectory tree as your primary, you can skip on ahead to the section entitled <a>“Prepare the Secondary Domain”</a> later in this chapter. If, per chance, your secondary domain is in a different eDirectory tree than your primary domain, you should first go to the section below entitled <a>“Extending your eDirectory Schema”</a>.
If you do not have at least ConsoleOne 1.3.6h installed on the administration workstation, for your secondary domain, you should install it now. While there is an installation routine in the GroupWise setup that allows you to install ConsoleOne and the snapins during the installation of your agent software, we want to go ahead and check the schema of your eDirectory tree before we jump into the actual upgrade. If you already have ConsoleOne 1.3.6h or greater installed, you can skip to <a>“Updating Your ConsoleOne Snapins”</a> below.
Locations for Administering GroupWise
For those of us who are long time GroupWise on NetWare administrators, the question of where to place ConsoleOne seems very straightforward. We run it from our workstations of course! And certainly if you have GroupWise 2012 on Windows servers or Linux servers you can continue to administer GroupWise directly from your workstation, provided that you have direct file access to the server housing GroupWise. For Windows of course this would mean that you must have file access from your workstation to your Windows server. For Linux the same thing applies, but can be much more confusing. If you are running GroupWise on OES2 Linux, you can serve up your GroupWise volume as an NCP volume (regardless of the file system you are using), and map that drive just as you would a NetWare drive. If you are running GroupWise on SLES, you would need to load SAMBA and mount the drive from your Windows workstation as though you were accessing a Windows server. UNDER NO CIRCUMSTANCES should you serve up your GroupWise volumes under Linux as an NFS mount. This can cause serious file locking issues, and ensuing corruption of your GroupWise databases.
Even though it is possible to administer your GroupWise system on Windows or Linux from your local Windows workstation, many administrators choose to run ConsoleOne directly on the GroupWise server itself. To install ConsoleOne on your Windows server, install ConsoleOne and the snapins on the Windows server the same way as you do your Windows PC. Instructions for installing ConsoleOne on both Windows and Linux follow.
In your Master SDD created above, you will find a directory called “ConsoleOne”. Run the install.exe program in this directory to install ConsoleOne on your administration PC. By default this is c:\novell\consoleone\1.2. If you have located this somewhere else on your PC (for example on d:), the installation routine should detect this. It is a good idea to double check this during installation to avoid having two separate versions of ConsoleOne on your PC unless you wish to have two versions for some special purpose. The installation will create a shortcut to ConsoleOne if this does not already exist.
In your Master SDD created above, you will find a directory called “consoleone”. From a Linux terminal prompt, change to your Master SDD (in our example below /grpwise/gw12soft) and perform the following commands:
You will now go through the installation routine for ConsoleOne on your Linux server. ConsoleOne on Linux is launched by running /usr/ConsoleOne/bin/ConsoleOne.
<a id="Anchor-26"></a>Updating Your ConsoleOne Snapins
<a id="Anchor-26"></a>Once your version of ConsoleOne is at 1.3.6h or greater, you also need to update your ConsoleOne snapins for GroupWise 2012. You can do this during your initial domain software installation (see <a>“Installing your Agent Software”</a> below), or you can do it manually from your SDD. Whenever you receive new GroupWise software, it is not really necessary to run the installation routine to update your GroupWise snapins. While it is convenient to do so if you are in the midst of installing the GroupWise agents anyway, if you need to roll out the snapins to multiple PCs, you can simply follow these steps:
In your Master SDD under the Admin directory, there is a C1ADMIN directory. Under there you will see directories such as bin, snapins, etc. The “simple” way to update your ConsoleOne snapins is to copy all of these directories into the c:\novell\consoleone\1.2 directory (assuming that is where you have installed ConsoleOne). Under that directory are also directories called bin, snapins, etc., and you will be prompted if you should overwrite those directories. Answering in the affirmative will copy the new snapins into the ConsoleOne structure and you will be ready to go!
NOTE: Some manual updates of the snapins might fail due to missing VS2005 runtimes. If you run into a problem with ConsoleOne after manually copying the snapins, run <SDD>\gwinst\vcredist_x86.exe.
For the most part, it is easiest in Linux to just run the install routine and choose to install the GroupWise Administration. However, this will frequently force you to upgrade all other GroupWise components on that server, so we’ll show you how to update the snapins manually. From a Linux terminal prompt, as root change to the installation directory for the snapins as follows:
rpm -Uvh NOVLc1Linuxjre-1.5.0-11.i586.rpm
rpm -Uvh novell-groupwise-admin-12.0.0-97810.i586.rpm
This will install your ConsoleOne snapins. Please note that the file names above are the file names as currently listed in the GroupWise 2012 download. These will change with new versions of GroupWise as they are made available via download. Substitute the versions of these files as necessary. If you see dependency errors on trying update the snapins, add the –force switch to the command. For example:
rpm -Uvh –force novell-groupwise-admin-12.0.0-97810.i586.rpm
NOTE: Sometimes people ask us when they should install the GroupWise 2012 snapins in preparation for an upgrade. We usually recommend that you install the snapins when you are ready to upgrade any domain that you administer. For example, if you are on an distributed system, and there are many administrators, upgrade the snapins for the administrators as domains they manage are upgraded. While it is safe to use GroupWise 2012 snapins on older systems, you may find that the snapins for some functions will change. For example, the GWIA snapins do not check to see if you are using a GroupWise 2012 GWIA and will show you options that might not be available for a GroupWise 8 or earlier GWIA. It is just less confusing to wait until you need the GroupWise 2012 snapins to install them. That said, however, once you upgrade your domain to GroupWise 2012, you should use those snapins any time you access a GroupWise 2012 domain, so it will be necessary to roll these snapins out to all locations that might access the GroupWise 2012 domain.
<a id="Anchor-19"></a>Extending your eDirectory Schema
If your secondary domain is in the same eDirectory tree as your primary domain, your schema has already been extended, and you can skip this section. If, however, your secondary domain is in a different tree, you need to check your schema before going any further.
In Preparing for Your GroupWise Upgrade, we discussed the importance of making sure your eDirectory tree is in good health. GroupWise 2012 will likely need to extend your eDirectory schema, and you certainly do not want to attempt any changes to your eDirectory schema if anything is pending or problematic in the tree.
WARNING: Some of the worst “GroupWise” issues we’ve been called in to salvage had little to do with GroupWise itself, but were to fix problems that arose from making changes in the system that required modifying an unhappy eDirectory tree! While schema extensions will not likely cause any great harm to your tree if it is out of whack, it’s best to make sure that everything is replicating properly before you begin.
NOTE: Some minimal steps you can take to ensure that your tree is healthy are to do a “check synchronization status” in dsrepair from the root partition server and/or check the agent health in iMonitor.
If your tree is happy and healthy, you will need to extend the schema (or have a more powerful admin do so if you are unauthorized to access the root of the tree). In order to extend the eDirectory schema for GroupWise 2012, you must use ConsoleOne with GroupWise 2012 snapins. In ConsoleOne, click on your eDirectory tree name (not the GroupWise “system” icon), and under Tools choose GroupWise Utilities|Check eDirectory Schema. If you need to extend the schema, you will be instructed to do so. Just click next and let the schema update. There are no schema extensions if you are upgrading from GroupWise 8. It doesn’t hurt anything to always check though!
Enabling the HTTP Monitor for Your Agent
We have found that there are many GroupWise sites where the HTTP (Web) Monitor is not in use. Especially with GroupWise 8 and later, these HTTP Monitors have become more and more important. If you define a userid and password for the HTTP Monitors, you can perform all of the functions that you used to perform at the GUI Consoles for your agents, as well as new functions that were not available on the GUI Consoles. If you do not have your HTTP Monitor enabled, now is a good time to do so.
In ConsoleOne, click on the GroupWise System Globe, and perform the following steps:
When you are ready to continue your upgrade, we will first check the secondary domain database to make sure that it is ready to upgrade. First, in ConsoleOne, select the secondary domain object and choose Tools|GroupWise Utilities|System Maintenance|Validate Database. If your database shows as valid, you can proceed. If for some reason the database does NOT validate, you should rebuild it. In order to rebuild the database you must first shut down the MTA and any gateways that attach to the domain database. At this point, we are going to shut down these agents for the upgrade anyway, so if you need to rebuild your database, first follow the instructions immediately below on shutting down your agents. Once the agents are shut down, return to ConsoleOne, make sure you are connected to the primary domain database, highlight the secondary domain in question, and choose Tools|GroupWise Utilities|System Maintenance, and this time choose Rebuild Database.
On Linux, you must upgrade all GroupWise components at the same time, so you need to stop all processes that are GroupWise related. This includes all GroupWise agents, gateways and GroupWise Monitor. We are assuming that you are running your agents as daemons. If, however, you are running them with their GUI consoles, unload all of the agents by shutting down the GUI consoles. Close the GroupWise client if it is running on the server. Finally, to be certain that all agents and gateways are closed, type the following commands at a terminal prompt:
These are the three main scripts that control GroupWise agents and gateways on Linux (although grpwise-wa was moved into the grpwise script with GroupWise 8). You may receive errors if you are not using the grpwise-ma or grpwise-wa scripts, but it does not hurt to attempt to stop them even if you do not have these scripts installed.
After all GroupWise components have been shut down, type the following into the terminal prompt to verify that no GroupWise components are running:
ps -A | grep gw
If at this point you still see GroupWise components loaded you can kill them individually, either by pid or name – for example:
(if you show a GroupWise component with the pid 9860 running)
<a id="Anchor-32"></a>For Windows, you must also shut down all of your agents that access the domain database. If you are running the agents as services, go into the services console from the Control Panel, right click on the GroupWise agents, and choose stop (see <a>Figure 4-1</a>). If you are not running the agents as services, go to the agent consoles and exit via F7 or from the agent menus.
After your agents are shut down, leave them down until you are instructed to reload them below.
Overview of the Secondary Domain Upgrade
With GroupWise 8, Novell created a brand new installation routine geared towards helping newer GroupWise administrators to create a GroupWise system with all of the components necessary to get GroupWise up and running. This has continued with GroupWise 2012. For example, the installation routine allows you to install not only ConsoleOne and the GroupWise Agents, but also the GWIA. This will allow a brand new GroupWise Administrator to create a new GroupWise system, including the GWIA in one sitting, and get up and running more quickly. However, in changing the installation routine to streamline the work for a new administrator, some of our familiar installation routines have been removed, and we will have to rely more on the wizard that we might have in the past. But don’t despair! We will veer away from the wizard often enough to please the purists in the crowd!
NOTE: If Windows administrators look under the AGENTS directory, or the INTERNET/GWIA directory you will find that there are no longer any installation programs for the agents or the GWIA individually. These components must all be installed from the setup.exe file found at the root of your SDD.
Depending on your setup, you may be simply upgrading your secondary domain during this sitting, or you may be doing more than that. If any other GroupWise components exist on the same server as your secondary domain, you need to upgrade them now too. Let’s look at the possible scenarios.
So, let’s get down to it.
<a id="Anchor-27"></a>Installing your Agent Software
In the sections above, we shut down the MTA, POA and gateways on your server. It is important that you have not reloaded any of these components since then, or if you did that you go back through the steps to unload the agents and verify that everything is down. Once the agents are unloaded, look in the root of the Master SDD we created earlier.
If you are running your domain on Windows, you must run this installation directly on the Windows server, rather than from a workstation attached to the Windows server.
<a id="Anchor-27"></a>In the root of the Master SDD, you will see the setup.exe program that will be used for this upgrade. When you run this program, you see the Window in <a>Figure 4-2</a>.
You will notice that at this point you could also choose to install the GWIA files as well, but we prefer to do this in a separate step, so keep this option unchecked for now.
NOTE: If you do choose to keep the new default that Novell suggests, you MUST reconfigure your agents. Otherwise there will be no startup files created for your agents in the new location, and your existing Windows services will point to the wrong location for the executable files.
<img alt="install4.tiff" src="file:///Volumes/Data/danita/Documents/publishing/gw2012upg/2ndDomains-web-images/install4_opt.jpeg" width="693" height="518" />
Running the Linux installation routine is a bit different, in that you are not allowed to pick and choose what you install when running this installation script. The script will detect what GroupWise components are already installed on this server, and it will insist that they all be updated at the same time.
In your Master Linux SDD (in our case /grpwise/gw12soft), run the install script as root. For example:
gwlinux:/grpwise # ./install
You will see the screen in <a>Figure 4-6</a>.
<a id="Anchor-12"></a>NOTE: <a>Figure 4-8</a> shows a number of agents installed on this server. If you have a simple, single server system, you may see all of these. If you have multiple servers, you will only see the agents required for the particular server being upgraded. With the changes to WebAccess, not only do you not see the WebAccess Agent listed (as it is now obsolete), but you do not see the WebAccess Application either. You will be required to do a separate installation for WebAccess if it is on the same server.
<a id="Anchor-28"></a>Configuration of your Agents during installation
As we discussed above during the software installation, it is rare that you would need to configure your agents during a GroupWise 2012 upgrade. One reason might be that you wish to reconfigure your Windows services to run the agents from Novell’s new default Windows path.
If you feel the need to create a new a new startup file for your domain, you can do so during the installation of the agent software for Windows. A Linux install works slightly differently, and we will discuss that next.
<a id="Anchor-28"></a>When we ran through the installation routine above, we checked the box in <a>Figure 4-5</a> that said to “ Install files but do not configure agents”. This bypasses the creation of the agent startup files and the defining of Windows services or shortcuts. We assume that this is the best option for an upgrade, because you should already have agent startup files and Windows services defined (or shortcuts in your startup folder), depending on the server OS. However, just to be thorough, we will go through the configuration steps for you in case you are having problems, or just wish to redo these options. Let’s go through these steps now.
When you reach <a>Figure 4-5</a> above, do not check the option to “Install files but do not configure agents”. Instead now you have the option to “Install and Configure SNMP for GroupWise Agents” and “Install as Windows services”.
Install and Configure SNMP for GroupWise Agents
If you have SNMP installed on your GroupWise server, you can configure SNMP for the agents on this server.
Install as Windows services
It is highly recommended that you install your GroupWise agents as services on your Windows server. If you do not, you must log into the Windows server and launch the agents on startup. Otherwise the agents cannot launch and users will not be able to access GroupWise until the login takes place.
After you choose the options on this screen you will click next and be presented with the window in <a>Figure 4-9</a>.
While we are looking at this screen, we should explain its usage so that it’s more easily understood the next time you encounter it. There are a few misconceptions about what is done here, and what you need to put in this location, so we will try to clear those up.
<a id="Anchor-23"></a>First, this screen is a template for creating new agent startup files (for example the domain.mta file), and for configuring your Windows services or Windows shortcuts. Let’s take the example of our groupwise system. Our secondary domain is called CNC. If we want to create a new startup file for the CNC domain, and configure Windows services and shortcuts, we would click the Add button as shown in <a>Figure 4-10</a> and enter the information for our domain.
<a id="Anchor-24"></a>By entering this information, we are instructing the installation routine to create us a startup file called cnc.mta with a /home switch of “w:\domains\cnc”, place it in the location of our startup files that we indicated in <a>Figure 4-5</a> above, and optionally configure a Windows service for the MTA or create a Windows shortcut.
This screen will validate the location you specify and warn you if you are putting in an invalid location (for example, if you put in m:\domains\cnc and that location does not contain a domain database it will complain). Interestingly enough though, if you “cancel” at this point, it will still put m:\domains\cnc in the setup and will complain that the path is invalid when you click “Next” to continue the setup. You will be required to fix this to point to a valid domain location before you can complete the setup. The installation does not validate the “name” you put here and indeed, you can name things here anything you like. For example, rather than naming my startup file “cnc.mta” as shown above, I could just as easily type “Domain2” in the name field, and the name of the file would instead be domain2.mta. If you put in a name that has more than eight characters (for example Caledonia), the file name will be truncated to eight characters. So, if indeed I were to put “Caledonia” in the name of my domain field, I would have a startup file called “caledoni.mta”. If a “caledoni.mta” file already exists, I will now have a “caledoni.mt1” file in that directory.
If your Secondary domain is the only domain and there are no post offices on this server, you are finished adding agents. If you also have a post office on this server, you can click add again, change the type to Post Office and enter the information here for your post office.
To configure the Linux agents, the steps are similar, but you approach the process somewhat differently. In <a>Figure 4-7</a> you were shown how all of the Linux installation screens have both an “install” and a “configure” option. To configure a Linux agent, click on the Configure Agents option. Click next on the introduction screen and accept the license agreement. You will be presented with a window similar to <a>Figure 4-9</a> (just a bit more “Linux-like”).
This screen is a template for creating new agent startup files (for example the cnc.mta file), and for configuring your Windows services or Windows shortcuts. Let’s take the example of our groupwise system. Our secondary domain is called CNC. If we want to create a new startup file for the CNC domain, and configure the grpwise script (provided that we checked the option above to “Launch the GroupWise agents on system startup), we would click the Add button as shown in Figure 3-10 and enter the information for our domain.
This screen will validate the location you specify and warn you if you are putting in an invalid location (for example, if you put in /groupwise/domains/cnc and that location does not contain a domain database it will complain). The installation does not validate the “name” you put here and indeed, you can name things here anything you like. For example, rather than naming my startup file “cnc.mta” as shown above, I could just as easily type “cnc-dom” in the name field, and the name of the file would instead be cnc-dom.mta.
If your secondary domain is the only domain on this server, and there are no post offices on this server, you are finished adding agents. If you also have a post office on this server, you can click add again, change the type to Post Office and enter the information here for your post office.
<a id="Anchor-29"></a>Upgrading Your Secondary Domain
At this point, you have installed the software required to take your domain to GroupWise 2012, but your domain has not actually upgraded. This will not happen until you load the new software, under the proper conditions. Earlier in this chapter we saw an option on the Novell installation routine that said “Update an Existing System” and we chose to skip that. Novell’s installation routine has improved quite a bit with GroupWise 2012, but it still expects certain aspects of every GroupWise system to be uniform, and we find that more times than not, GroupWise systems simply are not! This causes inconsistencies in the upgrade process, and it is easier for us (and you) to do these steps manually to ensure that they are done correctly in every single upgrade. This makes just one or two fewer things to have to troubleshoot if there are problems. In order to continue our upgrade, do the following:
Of course, use the location of your installed agents in this command.
Linux: For all Linux installations, the agents are installed to run as daemons. You can launch them under X-Windows to the GUI console during the upgrade just to see that everything loads okay. From a terminal prompt:
/opt/novell/groupwise/agents/bin/gwmta –show @domain.mta &
Your MTA should load up on your server. If you receive any errors during loading, check what the error is and see what can be done to resolve it.
<a id="Anchor-29"></a>When the GroupWise 2012 MTA for the secondary domain loads, it looks for the dc file that says it is okay to upgrade. The dc file is essentially a text file that contains the database schema for creating a GroupWise 2012 database. The gwdom.dc shows the version number at the very top line as #VERSION=1200. This version number at the top of the file verifies that you have the GroupWise 2012 dc file in your domain directory. Once the MTA sees the GroupWise 2012 dc file and notes that the domain is the secondary domain, the MTA will launch a recovery of the database, effectively converting the domain to GroupWise 2012. If you are quick (on a small domain – not so quick on a larger one), you will be able to see the Admin Status of the Domain change to “Recovering” to show that the domain is being converted (<a>Figure 4-12</a>)
Once the status returns to “Normal” you should be able to look at the properties of the domain in ConsoleOne and see that the version is GroupWise 2012. Once the secondary domain has been converted to GroupWise 2012 you can continue to upgrade the rest of your system according to your upgrade plan.
Where to from here?
Depending on the size and complexity of your system, and your overall upgrade plan, there are a number of “next steps” that you can take. The main run of thumb is that you must upgrade ALL components of GroupWise that reside on the same server. Let’s look at a couple of very common configurations that you might be looking at.
There are as many configurations of multiple server GroupWise systems as there are GroupWise customers it seems! So, we’ll just point out a couple of typical layouts, and send you on to your next step.
Secondary Domain and Post Office on the Same Server
If you have a post office on the same server as your secondary domain, you will need to go ahead and upgrade your Post Office before you are finished with this server. Because the agents installation always installs both the MTA and the POA, you will not need to go through the steps for installing the software again on your single GroupWise server! So, jump directly to the section on “Upgrading Your Post Office” in Chapter 9 to upgrade your post office. The rest of the Post Office chapter will discuss some new options for your Post Office that you might wish to enable.
Secondary Domain and Gateways on the Same Server
You might also have a Secondary Domain and gateways (such as the GWIA and/or WebAccess) on the same server, and other components on other servers. If this is the case, move on to Chapter 6, Upgrading Your GroupWise Internet Agent, or Chapter 7, Upgrading Your GroupWise WebAccess to continue your upgrade.
There are very few things that can go wrong during a domain upgrade. If you find that your Secondary Domain refuses to show as a GroupWise 2012 domain in ConsoleOne, do a couple of things:
Once you are ready to continue, just turn to the next chapter in your upgrade plan.