GroupWise Web 18.3 Best Practices

This is a comprehensive document that is evolving. The GroupWise 18.3 release is new. I work with the product daily and experience different issues with my customers and their individual environments. It's accurate to the best of my knowledge and I update/correct as needed.

I'm writing this guide based on the SLES 15 SP2 operating system. While SLES 12 and OES 2018 are also supported, you could experience variations in some of the commands. My preference is to use SLES15 SP2.

My goal is to offer information that goes far above and beyond what is included in the product documentation. This includes troubleshooting information as well as detail on what you should see when you have the system working correctly.

GroupWise 18.3 was released in December 2020 as a milestone feature release of GroupWise.  With this release, GroupWise introduces a completely new WebAccess experience called "GroupWise Web". This new application no longer uses Apache/Tomcat as the platform, and instead uses Docker Containers to run a self-contained WebAccess application. There are very few options and it doesn't take much to get going. However, in the normal fashion of GroupWise documentation, even if you RTFM, you'll be scratching your head a few times as you're working through things. I'm making the assumption that you've looked at the documentation that can be found here: https://support.microfocus.com/kb/doc.php?id=7022859

Although the general process of getting GroupWise Web up and running is fairly simple, there's a chance you could run into some problems or need further understanding of what's going on. I have color coordinated the different sections for clarity and split into the following general categories:

  • TLDR Version - Get up and running quick
  • Intro to Docker & Feature Parity
  • System Prerequisite How-To's
  • Firewall Requirements and How-To's
  • Full Installation Process
  • SSL Considerations
  • Troubleshooting

Too Long Didn't Read Version

This is the process from start to finish that is required to get the new GroupWise Web installed and configured. If everything works perfectly, this is all you need. If you're logged in as root, you do not need the sudo command.

Preparation

  • Create the folder /opt/novell/gw/certs
  • Copy your 3rd Party commercial certificates into /opt/novell/gw/certs
  • Rename your 3rd party certificate files to server.crt and server.key

Command Line Syntax

sudo zypper install docker 
sudo systemctl enable docker
sudo systemctl start docker
sudo docker run -it -v /opt/novell/gw:/config -e GWADMIN_SERVICE=admin@192.168.1.1:9710 -e GWSOAP_HOST_DEFAULT=192.168.1.2 mfgroupwise/web-config

sudo docker run -d --rm -v /opt/novell/gw:/etc/nginx/gw --name gwweb -e FQDN=webmail.redjuju.com -e DNS_SERVER=192.168.1.5 -p 80:80 -p 443:443 -v /opt/novell/gw/certs:/certs mfgroupwise/web:latest

Notes

Note the following items that must be customized to your specific environment:

  • "admin" refers to your GroupWise Administrator user credential. It is not necessarily "admin".
  • The IP Address referenced with the GWADMIN_SERVICE directive should be the IP address of your GroupWise Administration service.
  • 9710 Is the default GroupWise Admin port but could vary.
  • The GWSOAP_HOST_DEFAULT should reference the IP address of one of your GroupWise Post Office Agents. This may or may not be the same as your GroupWise Administration IP Address depending on your environment.
  • FQDN should be the full DNS name that users enter to connect to GroupWise Web from the Internet.
  • DNS_SERVER IP Address that docker will use for DNS Lookups.

The End Result / What To Expect

Below is a screenshot of the new GroupWise Web login screen. Although it does not mean everything is working perfectly, if you get this screen when connecting to GroupWise mail with an Internet browser, you can be confident that the new GroupWise Web application is running.

Working with Docker for GroupWise Web

I won't go into a ton of detail on Docker in general, but I will cover the basics for use in the GroupWise environment. Instead of installing an RPM module and configuring Apache and tomcat, Docker provides a prebuilt "package" that just runs. It works with a simple configuration file and minimal command-line options. Many applications are now being developed in this manner.

Helpful Docker commands:

Command Purpose
zypper install docker Installs the current Docker modules from the SUSE repositories
systemctl enable docker Enables the Docker service to launch on system startup
systemctl disable docker Prevents the Docker service from launching on system startup
systemctl start docker Starts the Docker service
systemctl stop docker Stops the Docker service
systemctl status docker Shows the running status of the Docker service
docker image list Lists the current Docker images
docker stop gwweb Stops the GroupWise Web application within Docker. Docker remains running.
docker rm gwweb Cleans up the GroupWise Web application from within Docker.
docker stop gwweb
docker rm gwweb
docker start gwweb
Generally used to stop, remove, and then start GroupWise Web.
Use this if you need to stop GroupWise Web, make changes or troubleshoot, then start it again.
docker restart gwweb Restarts the GroupWise Web application container.
docker pull mfgroupwise/web Downloads the latest version of GroupWise Web from the Micro Focus Docker repository
docker pull mfgroupwise/web-config Downloads the web-config utility from the Micro Focus Docker repository

Feature Parity GroupWise WebAccess vs GroupWise Web 18.3

It is important to understand that full feature parity does not exist between GroupWise WebAccess 18.2.1 and the GroupWise Web 18.3 initial release.

As a point of reference, it would seem pertinent to note that the GroupWise developers promised feature parity between the GroupWise Client and GroupWise WebAccess for years, but never fully achieved this even with GroupWise 18.2.1. Now with GroupWise Web replacing GroupWise WebAccess, the feature parity has gone backward.

Suggestions for how you might handle concerns about missing features:

  • Continue running GroupWise WebAccess and do not upgrade until more features have been built into GroupWise Web. The older GroupWise WebAccess will continue to function, it is not mandatory to upgrade it to continue to use it. Note that you may get pushback from Micro Focus support if you open a support ticket, and it's unlikely any bug fixes will be provided.
  • Run the GroupWise 18.2.1 WebAccess simultaneously alongside GroupWise Web 18.3 (using different servers)
  • Suck it up and just upgrade to the GroupWise Web 18.3 and wait for Micro Focus to roll out the features as they are available.

Prerequisites and System Requirements

It's easy to skim over the system requirements and assume everything is set correctly in your existing GroupWise environment. If you do this with GroupWise Web, you will be in for some challenges. Please review the system requirements and confirm that you meet each requirement.

In summary, the requirements are as follows:

  • Docker 19.03.5 or later on any Docker supported platform.

  • GroupWise 18.3 or later system.

  • GroupWise POA with SOAP enabled. SOAP must have SSL enabled.

  • GroupWise DVA with SSL enabled. ** This is likely going to be where you have issues **

  • (Optional) TLS certificates for GroupWise Web.

I have provided detailed notes on how to ensure that your system is configured to meet these requirements below.

Docker 19.03.5 or later on any Docker supported platform.

Note about Multi-Server environments:  In a multi-server GroupWise environment, the Docker requirement is only necessary for the actual server running the GroupWise Web application. Docker does not need to be installed on any other server.

To identify the Docker version, use this command at the Linux command line:

rpm -qa|grep docker

This should produce a list of all RPM's that contain the text "docker", and one of them will show the version number. In the results below from my fully patched SLES15 SP2 system, the version of Docker is 19.03.11.

mhcfs02:/ # rpm -qa|grep docker
docker-runc-1.0.0rc10+gitr3981_dc9208a3303f-6.38.2.x86_64
docker-bash-completion-19.03.11_ce-6.34.2.noarch
docker-19.03.11_ce-6.34.2.x86_64
docker-libnetwork-0.7.0.1+gitr2902_153d0769a118-4.21.2.x86_64

NOTE: If no results are returned, Docker is not installed at all. This is normal if it's a new install. The instructions for installing and enabling Docker are further below in this same document.

GroupWise 18.3 or later system.

To ensure your system is running GroupWise 18.3 or later, use this command at the Linux command line on all servers that are running GroupWise Agents (Post Offices and/or Domains):

rpm -qa|grep groupwise-server

This should produce the rpm module that is installed for the GroupWise software. The resulting output should show you the GroupWise version you are running as shown below:

mhcfs02:/ # rpm -qa|grep groupwise-server
groupwise-server-18.3.0-137352.x86_64

A couple points of clarification for this requirement.

  1. There's an entire best practice process for a GroupWise 18.3 system upgrade and it's not included in this document.  However, the general recommendation is that the GroupWise WebAccess or GroupWise Web application should be upgraded/installed after all domains and all post offices have been upgraded.
  2. In a multi-server GroupWise system, if GroupWise Web will be running on it's own separate and/or dedicated server, you likely do not and will not have the "groupwise-server" modules installed on that server. Check the versions on the servers that are actually running GroupWise agents.

GroupWise POA with SOAP enabled. SOAP must have SSL enabled.

It's very likely you meet this requirement already. But you should confirm the configuration anyway. Points to consider:

  • SOAP needs to be enabled on ALL Post Office Agents.
  • Enabling SSL on the SOAP protocol on your Post Offices is all or nothing. Meaning it's either enabled for ALL applications that use it or it's not enabled. You cannot mix and match between enabled and not enabled. For example, you cannot have SSL enabled on SOAP for use by GroupWise Web if GroupWise Mobility is set to use SOAP via non-SSL.
  • To my previous point, If you do not use SSL for soap, you MUST configure and enable it in order for GroupWise Web to function. You must ALSO consider all other applications that may use SOAP. For any application in your organization that connects to GroupWise via SOAP, you MUST enable SSL on the SOAP protocol. Some applications that use SOAP:  Legacy GroupWise WebAccess, GroupWise Mobility Service, and the new GroupWise Web application.

Generally speaking, you can confirm that SOAP is configured to use SSL by looking at the running configuration on each Post Office agent. You do this in the POA Web Console that can be launched from the GroupWise Administration page.

GroupWise POA Configuration Settings
Internet Protocol Agent Settings:
IMAP Agent: Enabled
IMAP Port for Incoming IMAP requests: 143 (Default)
IMAP over SSL: Enabled
IMAP SSL Agent: Enabled
IMAP SSL Port for Incoming IMAP requests: 993 (Default)
IMAP Read Limit: 4000
IMAP Read New: Enabled
SOAP Agent:  Enabled 
SOAP Port for Incoming SOAP requests:  7191 
SOAP Proxy Port: 7191
SOAP over SSL:  Enabled 
SOAP Redirection Table:  Show

If you find that SSL is not enabled on the SOAP protocol, you will need to install a certificate/key pair on each Post Office agent and enable SSL for SOAP on the agent configuration. SSL configuration is out of the scope of this document.

GroupWise DVA with SSL enabled

When SSL is not enabled on the DVA, GroupWise Web will function but you won't be able to view PDF or other docs from within the GroupWise Web application.

Things to understand about the GroupWise DVA:

  • The GroupWise DVA is what allows you to view PDF, DOC, and Image files from within GroupWise.
  • Each Post Office generally has it's own DVA.
  • The GroupWise DVA is not enabled for SSL by default.
  • All DVA's in your entire GroupWise system need to have SSL enabled.
  • A defective Administration Console makes you think you're enabling SSL on the DVA but it actually does nothing (As of this writing).

If this requirement is not met, you'll experience the two things below.

When SSL is not enabled on the GroupWise DVA, you will receive an error that states "Unable to view attachment" as shown below.

When SSL is not enabled on the GroupWise DVA, you will see the following in the Docker log files when you experience this error.

2021/01/05 08:43:41 [error] 16#16: *43 SSL_do_handshake() failed (SSL: error:1408F10B:SSL routines:ssl3_get_record:wrong version number) while SSL handshaking to upstream, client: 172.17.0.1, server: webmail.redjuju.com, request: "POST /dva HTTP/1.1", upstream: "https://192.168.0.147:8301/dva", host: "webmail.redjuju.com", referrer: "https://webmail.redjuju.com/gw/mailbox/default"

Refer to the Troubleshooting/Log Files section below for information on how to configure and view the log files.

The SSL Certificates used by the DVA can be the same as the ones your GroupWise Agents use, but it is not required. Furthermore, it's adequate to use Self Signed certificates. You can also use 3rd party commercial certificates, and it could technically use the same certificate as what you use for your HTTPS Web interface. The distinction needs to be made that the DVA and other GroupWise agents require a password on the private key, but your HTTPS Web interface does not use a password on the private key.

How to configure the GroupWise DVA with SSL Enabled

This two step process enables the GroupWise DVA with SSL using a self signed certificate:

1) Creating the Certificate

Creating the certificates can be accomplished entirely from a SLES 15 Linux command line. The filenames I use are dva.crt, dva.key, and dva.crt.  The dva.nopass.key in the first step named "dva.nopass.key" for clarity that it does not have a password at that step.

I like to ensure that I'm in a folder that I have created just for certificates so that I do not get them confused with any other files or certificates.

Create CSR File and Private Key
This command will create the necessary Certificate Signing Request (CSR) and also generate the necessary Private Key file. Note that in this step, the private key file does not contain a password.

openssl req -newkey rsa:2048 -nodes -keyout dva.nopass.key -out dva.csr