Installing the GroupWise Administrative Service

The GroupWise Administration Service (sometimes referred to during installation as the GroupWise Server) is a new process that runs on each GroupWise server that houses agents. Installing the Administration Server is the first thing you will do on any server as you work through your upgrade. This cannot be done in advance for an in-place upgrade as it replaces the agent binaries. Since you are doing an in-place upgrade, you will complete this process immediately prior to performing your upgrade. Once you begin installing the Administration Service, files will be changed on your server that will require you continue your upgrade immediately after installing the Administration Service You should install the Administration Server to your new GroupWise server prior to beginning the migration. This will allow you to have dbcopy installed, as there is no longer a separate dbcopy installation, and dbcopy is instead included as part of the Administration Server installation.

As we move through this upgrade guide, you will learn more about the functionality and purpose of the GroupWise Administrative Service.

The Administrative Service is installed at the same time as the GroupWise agents, and must exist on any server where GroupWise 2014 agents are running. You should start to think of the Administrative Service as a core component of your system.

The initial step in upgrading your GroupWise system is to install the GroupWise Administrative Service, so that it can be prepared to manage the newly upgraded GroupWise system.

In the following section we will show how to install the Administration Server on both Linux and Windows. We highly recommend that your server OS is fully patched before you install the GroupWise Administration Service.

Installing the GroupWise Administration Service on Linux

Download the Installation Media

The first thing you need to do is access the GroupWise 2014 installation media. This will typically be a downloaded compressed file from either http://download.novell.com, or from your Novell Customer Center portal.

Copy this compressed file to a location on your GroupWise server and extract it. To extract the GroupWise tar file, you would use the following command:

tar xfvz nameofgwfile.tar.gz

then cd into the name of the resultant directory. The directory is generally named gw14.0.0-build_full_linux_multi.tar.gz

This is the perfect time to point out that even though the files are typically named “multi”, there is no longer an English-only version. Let’s look at the directory structure as it now exists.

sidebyside.tif

Old and new directory structures

As you can see here, there are a few directories missing from what you are accustomed to seeing. Indeed the directory layout is quite different. Gone are the domain and po directories that held the .dc files. WebAccess has been moved under Webapps. Monitor has been relegated to the “gwinst_legacy” directory! Now, in theory, it doesn’t really matter that the entire folder structure has changed, because you will just be installing everything with the script (renamed from just “install” to “install.sh”). In practice, we wish sometimes that we could just go grab the dbcopy rpm and install it manually, rather than having to go through some other hoops.

If you have been a “do it manually” type in the past, Novell has made it much more difficult for you. There is no gwcheck rpm to install manually. There is no dbcopy rpm to install manually. Everything is included in the “server” installation. For all but the most hands-on types (and the rare instances where something just “goes wrong”), using the wizards and installation scripts will work out just fine! That said, if you just really want to see what is “there” without performing an installation, you could do the following by changing to the server installation directory):

cd /server/linux/x86_64

then run

rpm2cpio novell-groupwise-server.64bit.rpm | cpio -idmv ./pathtodir/*

Note the . before /pathtodir/ is important.

You can even do the following to extract all files matching a pattern

rpm2cpio novell-groupwise-server.64bit.rpm | cpio -idmv .*pattern*

so you could use

rpm2cpio novell-groupwise-server.64bit.rpm | cpio -idmv .*dc

This would allow you to extract the .dc files to your current directory, should they somehow become corrupted or lost from your installation.

During the installation, all agents controlled through the gwha.conf file will be shut down.

Also, the installation procedure will attempt to refresh all software repositories and perform a check for certain required dependencies and updated files. We have found that if your server has no Internet connection, the installation can fail. While we do not run into this issue often, if for some reason you have no access to nu.novell.com from your server during the installation, you can turn off the repositories.

  1. Load YaST
  2. Choose Software|Software Repositories
  3. Click on each of the Repositories that show “enabled” and disable them.

Install the Administration Service

So, let’s install the Administration Service. Before we do, please note that if this is on a production GroupWise server, the installation will actually shut down all of your agents! So, if you’re not actually ready to upgrade your agent files, do not run this routine. After the installation, the new GroupWise 2014 agents will be loaded, but your databases will not have yet be upgraded. Thus you will be running GroupWise 2014 agents against your GroupWise 2012 databases.

In reality, even though all of this happens, the only thing that could break would be GWIA access as a POP3/IMAP4 server to your users. The 2014 GWIA is a “client”, and cannot access older Post Offices to fulfill POP3/IMAP4 requests. All other functionality would continue, even if your older domain and post office were using GroupWise 2014 agents. That said, you should not install the new GroupWise 2014 server until you are ready to upgrade.

  1. If you are in a GUI file browser like Nautilus or Konqueror, just click on install.sh and choose Run in Terminal (this is a text based installation, and will only run from the terminal). If you are at a terminal window, type ./install.sh in the directory where the script resides. Here’s the installation screen!
linuxinstall003.tif

The Installation Window

Notice that this is no longer a GUI installation. Everything is text based. In many builds of this installation routine, we have noticed that the arrow keys do not work, and you must use the tab key. If you have issues with arrowing around, use the tab and shift-tab.

  1. You have 5 languages to choose from here. Choose your language, and we’ll move on.
  2. At the next screen you will have two choices: Documentation and Installation. Documentation will attempt to open a web browser and take you to the Novell docs. Remember that the installation can be done in a totally text based environment, thus if you have no GUI/browser available to you, only the Readme be able to view if you choose to look at the documentation.
  3. The next screen will present you with the EULA. When you agree to the EULA you are moved to the following screen:
linuxinstall004.tif

The Main Installation Screen

  1. Here we can choose to install the GroupWise Server (i.e., all of the components necessary to run a GroupWise system), GroupWise WebAccess, GroupWise Calendar Publishing Host, GroupWise Monitor Agent or GroupWise Monitor Application. We’ll choose GroupWise Server.

The GroupWise server is responsible for installing the GroupWise Administration Service, as well as installing the software for the Domains (MTA), Post Offices (POA), GroupWise Document Viewer Agent (GWDVA) and Internet Agent (GWIA). Additionally, the Server installation installs dbcopy and gwcheck on the server as well.

  1. Next you have the option of Install or Configurei
linuxinstall005.tif

Installation Screen

We’ll of course choose Install. This will install the actual files. We will later go to configure.

The installation routine will immediately shut down all of the agents that are configured on this server, as listed in the gwha.conf file. It will then remove any unsupported files on this server. This includes the GroupWise 8 client for Linux (if it is installed on this server), as well as the ConsoleOne Snapins for GroupWise. While it is Novell’s contention that you will never need the ConsoleOne Snapins again on this server, we will show you in “Reinstalling ConsoleOne Snapins on Linux” on page 133 how to bring them back if you find yourself in a situation where you absolutely need them!

  1. After the agents are shut down, the installation will attempt to refresh nu.novell.com to look for any new versions of OpenMotif.
  2. GroupWise will then start installing OpenMotif and all of the required GroupWise files. During this process, the installation also creates a GroupWise Certificate Authority, and creates a certificate for the GroupWise Administration Service.
  3. Once the installation has completed, you will be prompted with “press any key to return . . .”. This will take you back to the Install/Configure menu.

After installing the Administrative Service, if you were to run an rcgrpwise status, you would see something like this:

windermere:~ # rcgrpwise status

Checking status [gwadminservice] running

Back at Figure 3-4 we can now choose Configure.

In prior versions of GroupWise, selecting “Configure” would launch a routine to configure your GroupWise agent startup files, and create the gwha.conf for your system. With this new installation process, the “Configure” option in the menu will launch the admin service, and present you with URLs to access for administration.

linuxinstall008.tif

The Configuration screen

You can copy the text on this screen for the URL in order to paste it into your browser. If you are installing in X, and have a browser available to you on the server, these URLs are actually clickable. It’s absolutely possible though, that you have simply ssh’d into the server to run the installation (since it needs no GUI), and will need to copy the URLs to your browser.

To access the Installation Console on Linux, continue with the section entitled “Accessing the GroupWise Installation Console”

Installing the GroupWise Administration Service on Windows

Download the Installation Media

The first thing you need to do is access the GroupWise 2014 installation media. This will typically be a downloaded compressed file from either http://download.novell.com, or from your Novell Customer Center portal.

Extract this file to a location on your GroupWise server. This is a zip file, and you can simply right-click on the file and choose “Extract All” to unzip the entire package to a directory of your choice. The files will then all be extracted into a folder named “groupwise”. Thus, if you were to choose c:\installs as the destination folder for the extraction, you would then have c:\installs\groupwise for your files.

This is the perfect time to point out that even though the files are typically named “multi”, there is no longer an English-only version. Let’s look at the directory structure as it now exists.

linuxinstall048.tif

Old and new directory structures

As you can see here, there are a few directories missing from what you are accustomed to seeing. Indeed the directory layout is quite different. Gone are the domain and po directories that held the .dc files. WebAccess has been moved under “Webapps”. Monitor has been relegated to the “gwinst_legacy” directory! Now, in theory, it doesn’t really matter that the entire folder structure has changed, because you will just be installing everything with setup.exe. In practice, we wish sometimes that we could just go grab the dbcopy rpm and install it manually, rather than having to go through some other hoops.

If you need access to the files prior to installation, you can extract all of the files to a temporary location to do so run:

setup.exe /extract path

so you could use

setup.exe /extract c:\gwtemp

During the installation, the GroupWise agents remain running, but a reboot is required to complete the installation.

Install the Administration Service

So, let’s install the Administration Service. Before we do, please note that if this is on a production GroupWise server, the installation will install the new agent software, RENAME your GroupWise services, and on reboot load everything back up! This will load GroupWise 2014 agents, but your databases will not have yet be upgraded. Thus you will be running GroupWise 2014 agents against your GroupWise 2012 databases.

In reality, even though all of this happens, the only thing that could break would be GWIA access as a POP3/IMAP4 server to your users. The 2014 GWIA is a “client”, and cannot access older Post Offices to fulfill POP3/IMAP4 requests. All other functionality would continue, even if your older domain and post office were using GroupWise 2014 agents. That said, you should not install the new GroupWise 2014 server until you are ready to upgrade.

Our Windows server is running a GroupWise domain, post office and GWIA. Notice the services that are running:

linuxinstall057.tif

GroupWise Agents

Prior to GroupWise 2014, when you installed agents on a Windows server, the services would be named after the startup files. So the services can be spread out all through the list. In the case above, we have a calpo POA, CNC MTA and a GWIA – without any easy way to find them in the list if you are not sure of the startup files names. This will change during this installation, and we will revisit this later in this setup.


Note: Since the GroupWise Agent Services have no description defined, one way to find them in the list is to sort the services by description. This makes them at least float to the top!


  1. From Windows Explorer, double-click on setup.exe in your installation directory. Here’s the installation screen!
    linuxinstall049.tif

    The Installation Window

  2. Here we can choose to install the GroupWise Server (i.e., all of the components necessary to run a GroupWise system), the GroupWise Client, GroupWise WebAccess, GroupWise Calendar Publishing Host, GroupWise Monitor, the GroupWise Free/Busy Service or the GroupWise MMC Plugins. We’ll choose GroupWise Server. Other components will be discussed in future chapters.

The GroupWise server is responsible for installing the GroupWise Administration Service, as well as installing the software for the Domains (MTA), Post Offices (POA), GroupWise Document Viewer Agent (GWDVA) and Internet Agent (GWIA). Additionally, the Server installation installs dbcopy and gwcheck on the server as well.

During this time you will see a few popups for the installation of some required redistributables such as vcruntime and c++ . It can take several minutes before the GroupWise installation continues.

  1. You have 5 languages to choose from here. Choose your language, and we’ll move on.
  2. At the “Welcome” window, click next,
  3. The next screen will present you with the EULA. When you agree to the EULA you are moved to the following screen:
linuxinstall053.tif

The Custom Setup Screen

  1. Our only real option here is to decide whether to install the Client Auto-Update Repository, and to choose the location for our executable files. Space is cheap. We generally recommend that you keep the default and install all files.

You will be brought to a confirmation window, allowing you to cancel or go back before you begin the installation. Click Install to proceed.

Files will be copied, and you will be at the completion window.

linuxinstall054.tif

Completion Screen

  1. You will be prompted to restart your server when the installation is completed. If you keep the box checked for Launching the Administration service after the reboot, you will be brought directly to the Installation Console. The particular “token” that allows you to access the Installation Console (which we’ll discuss later in this chapter) will expire after 5 minutes. So you might as well uncheck the box and load up the Installation Console manually when you are ready.

By the way, it can take a good while for the Administration Service to load after the reboot. You’ll see a command window with “Waiting for the Administration Service to start . . . .” and then eventually your browser will load.

After installing the Administration Service and rebooting your server, go and take a look at your services again (click the Start button|Administration Tools|Services. You will notice that all of your GroupWise services have been renamed, and are now sorted together under “GroupWise”.

linuxinstall047.tif

We also have a new service called “GroupWise Administration. This new service, as well as the GroupWise 2014 agents are now running.

Now WHAT, you say? I’ve updated my agents, and my GroupWise 2012 (or earlier!) domain and post office are being accessed by 2014 agents? Won’t that hurt my system? For the short-term, the answer is no. If you DO have a GWIA on this server, and if users are utilizing IMAP4 or POP3, they will be unable to access their mailboxes (you’ve essentially installed a GroupWise 2014 client with the GWIA, and the newer client cannot access older POs). The SMTP service for the GWIA, and the MTA and POA will work just fine. In the figure below, notice that in our case we have a GroupWise 2014 agent running, but our domain database is still version 8.

linuxinstall058.tif

GroupWise 2014 MTA with a Domain database that has not yet been upgraded.

Re-enabling the GroupWise High Availability Agent on Linux

If you are moving/migrating your system, you will re-eanble the GWHA during the Monitor Installation.  Skip this section for now, and it will be included in the Upgrading GroupWise Monitor Section.

During the Administration Service installation, all GroupWise related executable files are also upgraded. This includes the GroupWise High Availability Agent on Linux. The original GWHA settings are not preserved. Thus you will be required to do a bit of reconfiguring. If you are moving your system from Linux to Linux, and you had the GroupWise High Availability Agent installed on your original GroupWise server, you will want to re-enable it after you install GroupWise Monitor on your new server. Please see the chapter on “Upgrading GroupWise Monitor”later in this guide for more information. During our preparations in “GroupWise High Availability Agent Considerations” on page 12, we had you copy your MA_OPTIONS line and place it in a text file for user in our reconfiguration.

After the Administration Service has been installed, check your GroupWise Monitor agent to verify it loaded (i.e. go to http://yourserver:8200). If the agent is loaded, and operational, go back to your Linux server and type:

rcgrpwise-ma stop

Now, go edit /etc/sysconfig/grpwise-ma. Look for the line that starts GROUPWISE_MA_OPTIONS. Replace the switches there with those that were in your MA_OPTIONS you saved earlier. Our line would look like this:

GROUPWISE_MA_OPTIONS=”–hauser gwha –hapassword gwhapassword –hapoll 120 –httpagentuser gwweb –httpagentpassword gwweb –httpmonuser gwmon –httpmonpassword gwmon”

Note that the option has changed from MA_OPTIONS to GROUPWISE_MA_OPTIONS.

Now start the Monitor Agent again:

rcgrpwise-ma stop

Test the High Availability Agent by shutting down one of your agents. For example, we might shut down the MTA on our system:

rcgrpwise stop CNC

What the status of the agent (either through the monitor or by running rcgrpwise status) to verify that the agent restarts.

Troubleshooting

The gwha service should still be configured. You can verify this by going to /etc/sysconfig and looking at the gwha file. Unless this file has a line that reads

disabled = yes

then the service is still enabled. If the above line has appeared, remove it.

If the Monitor Agent will not load, double check the hauser and hapassword switches. If you type them by hand, remember that it is hapassword, not hapass as Danita tends to type (over and over!).

Accessing the GroupWise Installation Console

The installation routine will also create two icons on your server desktop – one for GroupWise Installation and one for the GroupWise Admin Console.

linuxinstall059.tif

GroupWise Administration Icons

These shortcut icons work the same on both Windows and Linux.

Let’s take a moment to look at these URLs.

When the Administration Service is first installed, it is configured to run on port 9710. While you can change this later if you like, it is not our recommendation that you do. Some sites change the default ports as a type of security. Firstly, there are almost NO instances of a GroupWise agent being compromised. Secondly, if you change these ports around, it causes a great deal of confusion when GroupWise consultants try to help you (yes, we are thinking of ourselves here). Now, if you absolutely must change these, then we’ll show you how later, but consider why you might want to do this, and only change the defaults if absolutely necessary. The two URLs that are called by these icons are:

https://yourserver:9710/gwadmin-console/login.jsp

and

https://yourserver:9710/gwadmin-console/install/login.jsp

These two URLs show that the Administration Service is running on port 9710, and that you need to go to either /gwadmin-console/install or /gwadmin-console to login. We’ll have plenty of time to look at the Administration Console. Let’s talk about the installation option in some detail.

Our image in Figure 3-5 on page 31 above shows a token at the end of the installation URL, after the “login.jsp” portion of the URL. This is visible on the Linux installation. On the Windows installation, a command is passed on reboot that runs gwadmin-ipc to request a token and pass the token to the web browser to launch the Installation Console.

So just what is this token? The token is a way for the installation procedure in the Administration Console to authenticate you so that not just anyone can hit the installation URL and start to make system changes. This token is only good for about 5 minutes. Thus, if you walk away from this screen and then attempt to access the Installation Console, you will be given a new token to use for verification. We’ll show you how this works when we get to “Accessing the Installation Console for the First Time”below.

When you click on the URL to launch it in Firefox on your Linux server, or copy the URL to your own workstation browser, you will first be notified that the SSL certificate is untrusted. This, of course, is because the installation created a self-signed certificate in the steps above for your GroupWise system to use for the Administration Console and any agent that does not already have a certificate installed. So you will be warned that you are accessing an “untrusted” site, but can happily accept the certificate. If for some reason you get a time-out trying to access the Administrative Console right after installing the system, try again in a few seconds. You might simply be too fast for the Administration Service to have loaded in the background.

Accessing the Installation Console for the First Time

If for some reason you wait longer than 5 minutes to use this token, it will be invalid, and if you access the Installation Console, you will see the screen shown in the figure below:

linuxinstall010.tif

GroupWise Administration Icons

Notice that the command we’re told to run above is “gwadmin-ipc authorize 7o-abfl549w” – this shows a program “gwadmin-ipc” a switch “authorize” and the token. You can copy this string and execute it on your Linux or Windows server.

In Windows, Novell has added the <serverfiles>\admin to the Path in System Variables. On Linux, Novell has included an /etc/profiles.d/gwadmin.sh file to add the Path on Linux as well.

We will discuss the programs in the /opt/novell/groupwise/admin (c:\Program Files\Novell\GroupWise Server\admin on Windows) directory in more detail later.

Let’s look at the Installation Console now.

linuxinstall012.tif

The Installation Console

Here you can Install a new system, Upgrade an existing system, or add some components.

Changing the Installation Console Access Method

If you have a simple system, dealing with the token to install or upgrade your system doesn’t seem like a big deal. If you have a large system, it can become a bit annoying. So, let’s look at how you can bypass the token.

First, let’s look in the

/opt/novell/groupwise/admin

or

c:\Program Files\Novell\GroupWise Server\admin\

directory on your server. Here you will find a file called install.cfg. By default, the contents of the file will look something like this:

#Tue Feb 04 21:12:28 MST 2014

mode=token

We can change this with the gwadminutil.sh script or the gwadminutil.cmd file. There are three modes you can use for the Installation configuration:

      • token
      • user
      • disabled.

Token is the default, and you have seen how it works. Now let’s look at the other two modes.

Change to /opt/novell/groupwise/admin or c:\Program Files\Novell\GroupWise Server\admin. You can look to see all of the functions of gwadminutil.sh by running it with no switches (on Windows, just type gwadminutil.cmd instead). For example:

windermere:/opt/novell/groupwise/admin # ./gwadminutil.sh

GroupWise Admin Command Line Utility (14.0.0.114855)

Usage: gwadminutil <command>

Commands:

validate

recover

reclaim

reindex

rebuild

sync

convert

release

merge

setadmin

upgrade

ca

certinst

dbinfo

installcfg

services

config

We will look at all of these switches later in this guide. For now, we are interested in installcfg. So let’s run gwadminutil.sh (or gwadminutil.cmd) again with the installcfg switch to see the help screen for it.

windermere:/opt/novell/groupwise/admin # ./gwadminutil.sh installcfg

usage: gwadminutil installcfg [-u ] [-p []] -m

example: gwadminutil installcfg

Configure the admin service installation authentication

-m,–mode <mode> Installation mode (token|user|disabled)

-p,–password Install password (if mode is ‘user’)

-u,–username Install username (if mode is ‘user’)

If we run

./gwadminutil installcfg -m disabled

this would prevent any access to the Installation Console. Of course someone with proper access to this directory can change the mode, but this prevents someone from accidentally stumbling upon the URL and trying to muck around.

Let’s set the configuration to user:

./gwadminutil installcfg -m user -user gwinstall -p mypass

The resultant config file would look like this:

windermere:/opt/novell/groupwise/admin # cat install.cfg

#Tue Feb 04 21:25:29 MST 2014

user=gwinstall

hash=6b2e94d8c3c0f6c055eaa40daf8d0bb23f57305a

mode=user

You cannot simply edit this file and modify the parameters for user mode, since the gwadminutil performs a password hash and writes the hash value to the file rather than a password in clear text. You CAN however, copy this file to other servers. So if you will have many servers to upgrade over the course of your project, copying the file to each server will avoid having to deal with tokens as you move through your upgrade process. The user that you designate here is very much like the http monitor users – it is neither a GroupWise nor an LDAP user, and should be unique for the situation, and the password known to only those who need access.

The ability to copy a file with the hash means that your first level of security is to limit the people who have access to the /opt/novell/groupwise/admin or c:\Program Files\Novell\GroupWise Server\admin folder on any particular server. What could someone do with this information? Create a new GroupWise system, upgrade components before you are ready, and install new domains or post offices. However, protecting file level access to your server is your best defense here.

Now that we’ve installed the Administration Service, you can upgrade the objects on this server.