Consultant's Corner: Upgrading to GroupWise 8 - Part 4: WebAccess


"Nothing gained, there is, without some loss also to balance the scales." Yoda. GroupWise WebAccess definitely has a ton of new "gains" (read: Features) in GroupWise 8. But with the gain comes a bit of "balance to the scales". In this article I will go through the upgrade of both WebAccess components - WebAccess Agent and the WebAccess Application (Apache2/Tomcat4 part).

Remember in part 1, 2, 3 and 4 we upgraded our ConsoleOne, extended our eDirectory Tree schema, and upgraded our domains -Primary first, and any/all secondary domains then we upgraded post offices. This follows our upgrade process and leads us to the next logical step -upgrading WebAccess. Remember, all post offices need to be upgraded to GroupWise 8 before a WebAccess gateway can access it. Please review the upgrade process below then we will get to it.
NOTE: In the writing of this series Novell released GroupWise 8 Hot Patch 1 to fix some security issues with GWIA and WebAccess. I highly recommend the reader use this version to upgrade to GroupWise 8.

Upgrade Process

Here is the Best Practice process for upgrading GroupWise, in general. Here is my process outline for upgrading. Note those items in BOLD are what is covered in this article.

  1. Install new ConsoleOne 1.3.6H

  • Install the GroupWise 8 Snapins into ConsoleOne 1.3.6H

  • Update eDirectory Schema.

  • Create a new GroupWise 8 SDD

  • Upgrade the Primary Domain

  • Upgrade the Post Office(s) Secondary Domain(s)

  • Upgrade the Post Office(s)

  • Upgrade the WebAccess Gateways Domain(s), if you have them.

  • Upgrade the WebAccess Gateway (s) -Agent and Application (Webserver)

  • Upgrade the GWIA Gateway Domain(s), if you have them.

  • Upgrade the GWIA Gateway(s)

  • Upgrade the GroupWise Client

Upgrade WebAccess Agent

First, I assume you have already upgraded the WebAccess Domain. It's Best Practice to have a gate under its own domain with no other post offices under that domain. One might even have a domain that just hosts WebAccess and GWIA. The reason for the Best Practice is that sometimes the gateways will be, by their very nature, trouble. Having a gateway under its own domain makes it easier to reconstruct in the event of a failure.

Also, if your WebAccess gateway is under its own domain, you might consider not upgrading but just creating a new WebAccess gateway. If you do, be sure to delete the old one and make sure it does not load. Finally, backup's. Nothing much for the WebAccess agent to back up. In fact, I never backup anything when I upgrade the WebAccess agent. The WebAccess Application is different. I ALWAYS backup the Apache2/Tomcat and Novell directories. When I do this backup, I first make sure that Apache and Tomcat are unloaded and I unload Java. Then I just copy the directories to a temporary location. Ok let's upgrade.

Here is the process to upgrade the WebAccess Agent using the Wizard:

  1. Run: GroupWise Software| Setup.exe

  • Select: Install More Components

  • Select: Install WebAccess

  • Select: Yes, on the License

  • De-Select: GroupWise WebAccess Application and Next

  • Select: NetWare and,

  • Choose: A path for the Agent NLM files to be installed. I like to create a directory like: GW8 which tells me exactly what version I am running. Example: sys:\system\GW8

  • Select: Next. You will be prompted to unload GroupWise Agents. Make sure all agents running from the sys:\system\GW8 directory are unloaded, just in case. Select OK.

  • Select: IP Address and fill it in or DNS and fill in the proper WebAccess DNS entry. Set the TCP port for WebAccess. Default is 7205. I prefer to use the last 2 digits of the IP address for the last 2 digits of the port like so: TCP: 7201

  • Select: Next

  • Choose: A path to the WebAccess gateway domain. Example: Datavl:\gatedom

  • Choose: A name for the WebAccess gateway directory. Choose the current GroupWise 7 WebAccess Agent directory name to 'update' the WebAccess gateway. If you select a new name for the directory you will be creating a NEW WebAccess gateway.

  • Select: Next

  • Select: Yes. If you chose the existing GroupWise 7 WebAccess gateway directory, you will be prompted to 'update existing' WebAccess. If you chose to do a new WebAccess you will not get this message.

  • Enter: A user name and password for the WebAccess gateway. While the screen says it should be an existing eDirectory user, it does not have to be. In fact, I use a fake name: NONAME and a fake password: NOTNEEDED .

  • Select: Next

  • Select: Enable WebConsole and add a non-eDirectory user name and password. This is for the HTTP WebConsole.

  • Choose: A TCP port for the WebConsole. Default is: 7211. I like to use non-standard like 4801. The 01 is from the last 2 digits of the IP address.

  • Select: Next

  • Select: Next on the Installation Summary

  • Watch: Installation will start

  • De-Select: Launch Installation Summary and Start the GroupWise WebAccess Agent

  • Select: Finish.

  • Select: Finish on the Installation Screen. It's likely hiding behind some window on your pc.

  • Change: In ConsoleOne, in the properties of the WebAccess gateway, under the GroupWise tab, Identification page, Database Version attribute, use the drop down button to change the database to "8.0"

  • Load: At the NetWare System Console, load the WebAccess gateway and its parent domain MTA.

In the NetWare world the load would be something like: load sys:\system\gw8\gwinter @gateway.waa . Here I assume you installed the agents to a "GW8" directory and let the Installation file create an *.WAA configuration file for you. You may also use the "strtweb.ncf" file the Installation creates. Now let's look at loading the WebAccess Gateway into Protected Memory. You can either add the lines given below into the STRTWEB.NCF or type them out. In either case, you will need to update your AUTOEXEC.NCF.

Now if you are going to use Protected Memory for your WebAccess Agent, you will type the following for NetWare 6.5 sp4 to sp6, and sp8:
load restart address space=WA1 sys:\system\gw8\gwinter @wa1.waa

This assumes you call your address space WA1 (the name of the gateway) and assumes the 'load' directory on sys:\system\gw8

If you are using NetWare 6.5 sp7 then your lines will be:
load address space=WA1 sys:\system\gw8\gwinter @wa1.waa
protection restart WA1

The reason for the difference is in the syntax that was left out in NetWare 6.5 sp7.

Finally if you load in Protected Memory, then you need to make sure to ONLY unload the gateway agent using the following command:
unload address space=WA1

Once the WebAccess gateway agent loads a process is started that will load the GWDVA -Document Viewer Agent. By default, the GWDVA loads 5 worker threads. You will see both agents running now: WebAccess gateway and GWDVA. Also, you will want to load your WebAccess gateway domain MTA.

Here are few of the installation screens:

Click to view.

Figure 1: Upgrade WebAccess Gateway: Install More Components

Click to view.

Figure 2: Upgrade WebAccess Gateway: NLM installation path

Click to view.

Figure 3: Upgrade WebAccess Gateway: IP/DNS entry and TCP Port

Click to view.

Figure 4: Upgrade WebAccess Gateway: Domain and Gateway Directory

Click to view.

Figure 5: Upgrade WebAccess Gateway: Update existing directory and WebAccess Object

Click to view.

Figure 6: Upgrade WebAccess Gateway: Change to the GroupWise 8 Database

Click to view.

Figure 7: Upgrade WebAccess Gateway: WebAccess Gateway loaded and upgraded

Upgrade WebAccess Application

Since the Wizard does such a great job upgrading the WebAccess Agent, and because I have to cover the upgrade of the WebAccess Application, I will not cover the manual process for upgrading the WebAccess Agent. On to the WebAccess Application.

The GroupWise WebAccess Application on NetWare uses sys:\Apache2 and sys:\Tomcat 4. It also creates (if new) or overwrites files in the sys:\novell directory. Or rather, it use to. With GroupWise 8 WebAccess Application, a change has come. Now sys:\novell\GroupWise\WebAccess is the new location of the WEBACC.CFG. The WebAccess Application uses the sys:\Tomcat\4\webapps\gw\web-inf\web.xml file to lay out the 'path statements' to the new sys:\Novell\GroupWise\WebAccess\webacc.cfg. So if after you upgrade the WebAccess Application, and you cannot figure out why it's not loading the new WebAccess Application login window, look to the WEB.XML. Also, you may find that the sys:\Tomcat\4\webapps\ROOT\WEB-INF has a WEB.XML that may be calling the old WEBACC.CFG. Change the path and the issue will be resolved. Also, in this WEB.XML it will likely have a path to the old sys:\Novell\WebAccess\SpellChk.cfg file. You will have to change this to the correct path AND to the correct file "dictionaries.cfg" or else you will get an error on the NetWare Logger screen. A final thought here is that you can just rename this sys:\tomcat\4\webapps\ROOT\WEB-INF\WEB.XML file by adding a "-OLD" on it and that will fix the issue as well.

I have found over the years that it's best to use the Wizard to upgrade the WebAccess Application. There are just too many files and too many locations to copy them to that it's just a pain. So I will use the Wizard.

Here is the WebAccess Application Wizard upgrade:

  1. Backup: Apache2, Tomcat and Novell directories. At the NetWare System Console, AP2WEBDN will unload Apache2. TC4STOP will stop Tomcat. UNLOAD JAVA will unload java. This will completely clear all files used. Next, make a copy of the 3 directories to a temporary location.

  • Load: Apache2, Tomcat. At the NetWare System Console, run AP2WEBUP.NCF and TOMCAT4.NCF. The reason we load these back up is the Installation Wizard seems to work better/properly when it has to unload them.

  • Run: GroupWise Software| Setup.exe

  • Select: Install More Components

  • Select: Install WebAccess

  • Select: Yes, on the License

  • De-Select: GroupWise WebAccess Agent and Next

  • Enter: Path to the WebAccess Agent directory. The Installation Wizard needs this in order to get the encryption file: COMMGR.CFG. You will need a mapped drive to the volume where the directory exists.

  • Select: Next

  • Choose: Apache2 if you are installing on NetWare.

  • Enter: Path to Apache2 directory. This is located on sys:\Apach2. I again recommend a mapped drive to the sys volume.

  • Select: Next

  • Select: Language. Default is English. Next.

  • Choose: The Context where you want the WebAccess Application objects to be updated or created new. By default, the Wizard wants to install/update the objects under the parent domain of the WebAccess gateway. My recommendation is to NOT do that. Create an eDirectory container just for the WebAccess Application objects and point to it for the Wizard. Why? Well, what if you deleted the WebAccess gateway domain? You lose the WebAccess Application objects. So you would have to reinstall them.

  • Select: Next

  • Select: Ok if you want to use the existing WebAccess Application objects. Or, Cancel to go back and select a new eDirectory context. OK is my response.

  • Select: Next on the Installation Summary.

  • Select: Yes, to have the Installation Wizard unload the webserver -Apache2/Tomcat.

  • Select: Yes, to have the Installation Wizard replace sys:\Tomcat\4\webapps\gw files. You backed up Tomcat so you can always pull them back if you need them.

  • De-Select: Launch Installation Summary and Restart Web Server on the Summary screen.

  • Select: Finish.

  • Select: Finish on the Installation Screen. It's likely hiding behind some window on your pc.

  • Load: Apache2 and Tomcat. Use AP2WEBUP.NCF and TOMCAT4.NCF

  • Select: Logger screen. On the NetWare server, CRTL-ESC, 2 (Logger Screen). From here you will be able to see if Tomcat loads and has the latest GroupWise 8 parts.

  • Launch: A Browser. Go to the IP Address of the web server slash gw like so: . This takes you to the Language Screen for GroupWise 8 WebAccess. Then go to the IP Address of the web server slash gw slash webacc like so: . This takes you to the login screen for GroupWise 8 WebAccess.

  • Login: Login into WebAccess and make sure it looks/works as expected. You will need the WebAccess Agent up and running as well as the post office. Remember the WEB.XML file if you find Tomcat is not pointing to the correct sys:\novell\GroupWise\WebAccess directory.

NOTE: In the WEB.XML I have found for NetWare, that every line that has "sys:" ends up having duplicate "\\" lines. I personally go in an remove them. Not sure it makes a difference, but it seems like the GroupWise 8 Tomcat loads faster.

Here are a several screen shots for the upgrade:

Click to view.

Figure 8: WebAccess Application Upgrade: Choose the Application

Click to view.

Figure 9: WebAccess Application Upgrade: Path to current WebAccess Agent

Click to view.

Figure 10: WebAccess Application Upgrade: Wizard to use existing WebAccess Application Objects

Click to view.

Figure 11: WebAccess Application Upgrade: Wizard Unloads Web Server

Click to view.

Figure 12: WebAccess Application Upgrade: Replacing older WebAccess files

Click to view.

Figure 13: WebAccess Application Upgrade: Tomcat Loaded, GroupWise WebAccess Ready for Work

Click to view.

Figure 14: WebAccess 8 Language Screen

Click to view.

Figure 15: WebAccess 8 Login Page


Upgrading WebAccess Application is the one part of GroupWise I often dread. The reason is because it often overwrites customized Index.html's and other web server files. The WebAccess Agent on the other hand is an easy upgrade. Hopefully, this article has helped you out and eases your dread. The next article (and last in the series), will show you how to upgrade GWIA. In the meantime, "Mind what you have learned. Save you it can!"

Got comments or article ideas? Need help with GroupWise? Drop me a line at: . "The Force is strong in this one."



How To-Best Practice
Comment List
  • Thanks again.. a lot of info laid out easier than the Netware documentation.
    Please highlight 2 issues you bring up:
    (1) in Upgrading the Web Agent, step 15.. you suggest using a fake username "Noname" & password. The installation does - as you point out, ask for an eDirectory user. Whatever is placed here, will be preserved in cleartext in the Web Access Agent configuration file. (in my case.. WEBAC80A.waa ) . Not only is your recommendation great, but the GW doc staff should have an old-fashioned ruler across the knuckles for saving real user passwords in cleartext!

    Also, you do mention the issues between the newer config of Tomcat and the speller references. I followed your notes, but still had an issue with send/receiving from WebAccess. These two TIDs cleared the issue up for me.