Upgrading Your GroupWise Internet Agent

Upgrading your GroupWise Internet Agent is a fairly simple process. However, there are some challenges that are presented if you intend to have a “mixed” system (i.e., GroupWise 2012 AND older post offices) for any length of time. Here are the issues at hand:

  • Your GWIA cannot be upgraded to GroupWise 2012 until the domain that owns it is upgraded to GroupWise 2012.
  • When using the GWIA as a POP3 or IMAP4 “client”, it is indeed a client. You cannot access a GroupWise 8 or earlier post office with the GWIA via IMAP4 or POP3, If it is attempted, you will see a “login failed: D058” in your GWIA log.
  • On the other hand, if the GWIA is being used only for SMTP services, there are no issues with a mixed system.

So, as you can see, it’s a good idea to get your post offices upgraded to GroupWise 2012 on a scheduled roll-out so that you are not surprised by any of the possible issues with mixed post offices. That said, may sites operate in a “mixed” system quite nicely for an extended period of time. You must simply make sure that your plans take the above caveats into account. If you need to have POP3 services for all users in your system, you might consider having two GWIAs – one for the GroupWise 2012 users, and one for your older post office users. If you are using IMAP4, you might consider opening up IMAP4 directly from the post office agent, rather than using the GWIA if you have a mixed system (versions 6.0 and later of GroupWise allow for IMAP4 at the post office agent).


Preparing for the Upgrade

Before you can install the new software for the GWIA, you must shut down any and all agents on your server. Since this is a GWIA, you most likely at least have an MTA for the GWIA’s domain on the same server. Shut down any GroupWise components on this server before we proceed. Since we have just moved our domain during this process, it’s unlikely that you have any GroupWise components other than the MTA loaded. We will, however, go through all of the shutdown procedure for you just in case.



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 and 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 Linux 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:


/etc/init.d/grpwise stop

/etc/init.d/grpwise-wa stop

/etc/init.d/grpwise-ma stop


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:


kill 9860

(if you show a GroupWise component with the pid 9860 running)



killall gwia



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 Figure 6-1). If you are not running the agents as services, go to the agent consoles and exit via F7 or from the agent menus.


    1. services1.tiffStopping a Windows service


After your agents are shut down, leave them down until you are instructed to reload them below.


Installing your Agent Software

For a GroupWise Internet Agent, upgrading is essentially just installing the new software and reconfiguring the GWIA for your new server. For the Windows installation, those administrators who have been around awhile will notice something different right away. Under the SDD/INTERNET/GWIA directory there is no longer an install.exe program. Instead, we will use the setup.exe found at the root of the SDD.



In the root of the Master SDD, you will see the setup.exe program that will be used for this upgrade. If you are installing the GWIA on a Windows server, you must run the installation routine on that server.

When you run this program, you see the Window in Figure 6-2.


    1. install1.tiffThe main installation screen
  • Click on Install GroupWise System.
  • Click Yes on the next screen to accept the license agreement.
  1. Click Next on the next screen to do a standard install. You will see the window in Figure 6-3.


    1. installgwia.tiffInstall Wizard – GroupWise Components
  • Choose Install individual components, and then uncheck everything except GroupWise Internet Agent.
  • The next screen seems to be a holdover from the combined Windows and NetWare installation routines of the past, and has a single radio button for Windows. Just click next.
  1. The next screen will give you the option of where to install your files on your Windows server, and options for the installation.Notice that in our example in Figure 6-4 we have chosen the option to “Install the software files, but do not configure the Internet Agent”. This will avoid a lot of questions that we do not need to answer during this move.
  2. When prompted, enter the path to your domain, and the name of the directory for your GWIA.
  3. Next you will be presented with a summary screen showing your choices for the install, and the installation will proceed.
  4. When the installation has completed, do not launch the agent yet. We need to do a few things.
  5. Copy the gwia.cfg from your source server to both the\domain\wpgate\gwia directory, and the location where you installed your GWIA files, as determined in Step 7 above.Edit the gwia.cfg and change the /home and /dhome directory to point to the location of the domain on the new server.
  6. If you have special Access Control Rules defined, these are located in the gwac.db file. If you have moved your GWIA to this server, then these rules will have moved with you.



    1. Install Wizard – Installation Path Screen


Load the GWIA on the Windows Server

If you installed your GWIA as a service, you load it by going to the Services panel, right-clicking on the GWIA service, and choosing “Start”. If you did not choose to load the GWIA as a service, there will be an icon for the application in your Programs menu.



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. For example:


gwlinux:/grpwise # ./install

After choosing your installation language, you will see the screen in Figure 6-5.

    1. lnxinstall1.tiffThe Linux Install Screen.


  • Choose install products.
  • Choose GroupWise Internet Agent
    1. Choose Install Internet Agent. If you have more than one GroupWise object on this server, you should see a screen similar to Figure 6-6. This screen will show all components on this particular Linux server that must be upgraded.
      1. update.tiffComponents to Upgrade on Linux

NOTE: Figure 6-6 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.


    1. You must choose Yes for this option, otherwise the installation will simply close. Choosing Yes starts the update of all agents required on this server. If there are a number of agents, this can take awhile. Once the agents are installed, choose Configure Internet Agent.
    2. When prompted, accept the License agreement
    3. At the server information enter the information for your GWIA (See Figure 6-7). Note the Message Transfer Port. This is the port that the GWIA would listen on if you were talking IP to the MTA. The only reason you would enter this information is if you have multiple GWIAs and are providing for failover. Most sites will leave this at 0. In no case should you put 25 in this port field. Otherwise your GWIA will not work at all! You must also put in the DNS host name of your GWIA here.
      1. Figurel-d12.tiffGWIA Server Information Screen


  1. At the relay host screen indicate whether you send directly to the internet, or put in the information for your relay host.
  2. At the Internet Domain Name screen, put in your domain name. For example, caledonia.net. You can also choose to enter this later in ConsoleOne, but since you know the information it’s quicker to do it here.
  3. At the Domain Directory screen, put in the local Linux path location for your domain. Also verify the directory name for your GWIA. This is typically just “gwia”.
  4. Next you must authenticate to your eDirectory tree via LDAP. This is necessary even if you are already logged into eDirectory in ConsoleOne. It is easier if your LDAP server allows for clear-text passwords. Otherwise you must check the “Use SSL” box and have your certificate available to this server.


TIP: If you need to temporarily allow access to your LDAP server without SSL, edit the LDAP Group for the LDAP server in ConsoleOne and uncheck the box that says “Require TLS for simply binds with password”. You can turn it back on afterwards. Of course, if you have easy access to the SSL Certificate on your Linux server, you will not need to bother with this.

    1. At the Gateway screen, you will see the name of your GWIA (typically just GWIA), and you will be asked to enter the LDAP context for your GroupWise domain. You can browse for this if you like. See Figure 6-8.
      1. Figurel-d14.tiffGateway Object Configuration
  • Now, indicate that you want the GWIA to load at startup, and click Exit, and then exit from the GroupWise installation application.
  • Compare the gwia.cfg from your source server to the new gwia.cfg in the /opt/novell/groupwise/agents/share directory to ensure that all of the settings are as you desire. Note that whereas on NetWare the gwia.cfg used switches starting with a slash (/home, /dhome, etc.) on Linux these start with a double-dash (–home, –dhome, etc.).
  • If you have special Access Control Rules defined, these are located in the gwac.db file. These settings should have moved with you. If you have any trouble with these settings, you can always copy the gwac.db file from your NetWare server to the Linux server, ensuring that the file name is all lowercase.

As with the MTA, the first time we start a new GWIA 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 GWIA with the GUI console as standard practice. We will load our GWIA 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:

./gwia –show @gwia.cfg &

This should bring up the agent screen as shown in Figure 6-9.

    1. Figurel-d15.tiffGWIA GUI Console on Linux

As long as the GWIA looks okay, we can unload both the GWIA and the MTA (which is still loaded in GUI mode above) by pressing F7 and the console windows, and reload them as daemons.


Cleaning Up

A few things to remember about moving a GWIA.

  • You may need to change your MX records if the public IP address for your GWIA will change due to the move to the new server. Otherwise, you may have to change the natting at your firewall, or change the IP address that an anti-spam appliance or other GWIA front-end sends to.
  • You may need to change the firewall settings for outbound SMTP if you limit the IP addresses on your network that are allow to sent mail on port 25.
  • If your outbound IP address will change for your GWIA, you should also have your PTR (reverse dns lookup) changed to reflect this, as well as any SPF records that are maintained for your domain.


There are very few things that can go wrong during a GWIA upgrade. The only problems we typically see have to do with the following:

  • You attempt to upgrade the GWIA before upgrading your Domain
  • You change the location of the GWIA installation files during the installation (either accidentally, or on purpose) and then do not reconfigure the agent to update the startup files for the server.


New Options of Note

Delayed Message Notification

Beginning with GroupWise 8, when mail going out the GWIA is delayed, the GWIA generates a “transfer delayed” status that is entered into the properties of the senders sent item. GroupWise 2012 will allow you to configure your GWIA to send a “delayed message notification” to the inbox of the sender. This setting is found on the SMTP/MIME tab of the GWIA configuration in ConsoleOne. Check the box that says “Return Notification to Sender When a Message Is Delayed”.

Rule-Generated Messages

As with GroupWise 8, you can now configure the GWIA to block either rule generated replies, rule generated forwards, or both.

Internet Agent Web Console

As with the other agent Web Consoles, you can now control most GWIA settings directly from the Web Console. This makes it more important to put a user and password on your GWIA Web Console.


Once you are ready to continue, just turn to the next chapter in your upgrade plan.