Copyright © 2008 ‘bond’ Software Entwicklung GmbH. All rights reserved.

Trademarks:

Novell, GroupWise, NetWare, eDirectory are trademarks of Novell, Inc.

Windows, XP, Windows 2000, Windows Server, Vista are trademarks of Microsoft, Inc.

Linux is a trademark of Linus Torwalds.EMA is a trademark of Artec Computer GmbH.

All other trademarks are properties of their respective owners.

1  How it works

The Groupwise-EMA Connector (short GWEMACON) reads all received Messages from all mailboxes of one GroupWise postoffice. These messages will be sent to the E-Mail Archiving Applicanc (EMA) and stored there.

GWEMACON uses SOAP and IMAP to read the messages and SMTP to transfer the messages to EMA. To make sure, that every message gets transferred exactly once, GMEMACON uses the following:

1.1.1  Groupwise Retention

GroupWise has a special feature made exactly for such archiving tasks. Each mailbox has a timestamp, that tells the last time, the messages had been archived (there is another timestamp for backup purposes). After setting the Retention Flag in ConsoleOne (see Installation) GroupWise only deletes messages that are older than the Retention timestamp. GWEMACON simply queries the mailbox for all messages bedween ‘NOW’ and the timestamp. After storing that message, the timestamp will be advance to ‘NOW’.

1.1.2  Message filtering

To avoid multiple storage of messages, GWEMACOM uses filters. Especially internal messages (form one mailbox/user of the postoffice to another) will be transformed in a way that they have to be transferred to EMA only once. EMA itself has a single copy store and stores this message only once, no matter how may recipients it has.

GWEMACON can also store appointments, jobs and notes, as long as they have been sent from one user to another. Appointments, jobs and notes that the user creates for himself will never be stored, because the user can change them whenever he wants. The storage of Appointments, Jobs and Notes can be configured.

With the configuration, it is also possible to exclude the junmail-folder from archiving.

2  Installation

2.1  Prerequisites

2.1.1  Hardware

GWEMACON runs under Linux. So you need a Linux computer for installation. If GroupWise itself runs on a Linux box, the connector can be installed on the same server. If GroupWise is running on NetWare or Windows, you need an additional server.

When deploying GWEMACON stand-alone we recommed a server grade computer with a Pentium 4 (or equivalent) processor and at least 512 MB memory. GWEMACON does not need much disk space. Only the log files can grow large (depending on the log settings). The amount of available memory also delimits the size of the biggest message that can be stored: GWEMACON buffers the messages in memory (using the MIME-format for SMTP). The maximum size is about half the memory the Linux Server has.

GWEMACON also runs on virtualized machines. In fact it was developed on a SLES 10 running as a VM inside VMware Workstation. Due to the incredible possible variations of virtualisation solutions, support for problems that arise from virtualization is limited.

2.1.2  Software

GWEMACON was developed with SUSE Linux Enterprise Server (SLES) 10, Service Pack 1. It is tested on SLES 10, SP1 and 2 and on SLES 9 SP2 and 3. The connector should also work with the free versions (OpenSuse 10 and 11) and even with other distributions. These configurations are not supported and may require changes at the start/stop scripts.

If GroupWise is configured for encrypted communications with SOAP and IMAP, the OpenSLL Packets – including the development Package must be installed.

We recommend to use a default installation with GNOME as GUI.

GroupWise needs to have at least version 7, SP 2 on Linux and SP3 on NetWare. GroupWise on Windows wasn’t tested, but it should also have at least SP 2.

Important !!!

GWEMACON was tested only on SUSE Linux Enterprise Server 9 and 10.

Although virtualized versions did work in the testing environment, on some virtualization platforms users found strange issues. Because an exhaustive testing on all possible virtualization plattforms and host operating systems is not possible, we will not be able to support such configurations.

2.1.3  More

For the creation of the trusted Application key, you will need a MS-Windows (2000 or XP) workstation with Novell Client, because the library for the creation of the key is only available on Windows.

For the configuration of the connector, a Windows-based GUI application is available. Otherwise the configuration files can be created and changed using any text editor (Notepad, vi, joe, gedit etc.)

2.2  Doing the Installation

We describe and show the installation steps with GNOME, the installation with KDE respective in text mode is nearly the same.

2.2.1.1  Copying the Software

If you got the software on CD, insert the disk in the drive of your server (if your server does not have a CD drive follow the next steps as if you had got the Software on another way). On the desktop you should find an icon for the CD. Now open a terminal window (right click on the desktop, Open Terminal). Change to superuser mode with su and the password of root:

user@server:~> su

Now copy the archive containing the software to /opt:

server:/home/user # cp /media/GWEMA/gwemacon.tgz /opt

If your server does not have a CD-drive or you got the software on another way, copy the archive to /opt (e.g. using WinSCP from a Windows workstation.

2.2.1.2  Extracting the software

Now we unpack the content of the archive:

server:/home/user # cd /opt

server:/opt # tar xvzf gwemacon.tgz

Than you should remove the archive or move it to another position, because following the recommendations of LSB (Linux Standards Base) there shouldn’t be simple files in the /opt folder. – On the other hand: it’s ”your” server ….

2.2.1.3  Installing the scripts

To influence the system as least as possible, we create only two files (and one link) outside /opt/gwema. This happened by calling install.sh:

server:/opt # cd gwema

server:/opt/gwema # ./install.sh

With this, the connector is installed. The next paragraph explains how to customize the installation and is for Linux experts only.

2.3  Customizing the installation (for experts only)

With the bundling of all files and programms that make the connector, it is relatively simple to move these to another location (if someone finds a real and valid reason for doing so, please write to [mailto:info@bond.de info@bond.de]).

The location of the home folder of GWEMACON is stored in ”/etc/sysconfig/gwema”. On YAST-based systems (SUSE !!) the sysconfig editor can be used to change that location (YAST | System | sysconfig editor). On other systems one can use /etc/gwema.conf to store the location of GWEMACONs home directory.

The second file installed outside the home directory is the start/stop script ”bond-gwemad” (in ”/etc/init.d”) and the symbolic link ”rcbond-gwemad” in ”/usr/sbin”. This script controls one instance of the connector for each configured postoffice.

The connector only uses TCP client connections and writes its log informations with syslog, so it can be run with resticted user rights (currently the connector runs as ”root” by default). With the current versions, the connector needs write access to the directory containing the configuration files. To change the user, the script ”$GWEMA_HOME/bin/gwema” has to be modified. This script gets called by ”bond-gwemad” for each postoffice connection.

3  Configuring the system

After the installation of the connector, we have to configure the E-Mail Appliance and GroupWise for it.

3.1  Configuration of EMA

Connect and start the E.Mail Appliance using its own documentation (including configuration of external storage etc.). This manual only shows the necessary steps for configuring the connection to GroupWise with GWEMACON. Now open a browser and connect to EMA.

3.1.1  Mode of Operation (General -> Mode of Operation)

Select ‘Archive messages processed by local mail server’ and click ‘Save Changes’

3.1.2  Mail Server (General -> Mail Server)

In the field ‘Local Addresses’ you configure your Internet Domain names. This field must include the Internet Domain Name you configure at the connector later.

Make sure the Milter Interface is disabled.

Make sure ‘Disable Exchange Envelope Journaling’ is selected.

For the Address Detection Method, select ‘Detect Addresses from Header’ and add ‘X-EMA-’ in front of both headers shown.

Under Mail Server Configuration enter the address of GWIA as the EMA Appliance can see it. If you are using a NAT-Firewall, this is the internal address. Leave Username and Password blank.

For the return address, you can configure the addess of the administrator -as recommended- or a virtual address like ema@internetDomain.

For LDAP support chose ‘Disable LDAP’ for now.

3.1.3  Network (General -> Network)

Configure your specific Network connection data. (See also EMA Manual)

3.2  Configuration of GroupWise

To allow GWEMACON access to the GroupWise system, you have to configure a ”trusted application”.

Because of the pre-build DLL from Novell this is currently only possible on a Windows machine.

3.2.1  Prerequisites

You have to be logged in as admin to the eDirectory tree, that contains the GroupWise system (eDirectory supervisor rights to the GroupWise objects). You also need full file system access to the domain directory of the primary domain of your GroupWise system. It doesn’t matter whether this access is over NCP (NetWare, OES) or SMB (Windows, Linux with Samba).

3.2.1.1  GroupWise on Linux (without OES)

To configure a share on SLES, you have to activate Samba (it is installed by default). Open YAST (Network Services ? Samba Server) and configure a share for the domain directory.

Than open a terminal window and create a samba password for root:

server:/somewhere # smbpasswd -a

Now you can access that share using a Windows workstation. Connect a drive letter to the share and log in to eDirectory.

3.2.1.2  GroupWise on NetWare

This is the simplest case. Only log in as admin with eDirectory. Now assign a drive letter to the volume containing the domain directory.

3.2.1.3  GroupWise on Windows

On the Windows server create a share for the domain directory. Log in to eDirectory as admin with the Novell Client. Connect a drive letter to the Windows share. Use an account with all file rights (e.g. Administrator).

3.2.1.4  GroupWise on OES-Linux

If you GroupWise system runs on OES/Linux, simply create a NCP Volume for the domain directory using ”ncpcon”. Now you can login and connect a drive to the system as you would with classic NetWare.

3.2.1.5  Access to the program files

Now you need acces to the program files. These are located under ”/opt/gwema/win” on the server, where the connector has been installed. Alternatively you can extract them from the archive using a unpacker like 7Zip or similar.

3.2.2  Creating the Trusted Application

Now start GWEMATA.exe.

Click on the button behind ‘Path to Domain’ to define the location of your GroupWise domain directory:

For GroupWise on Linux, they are located under ”/var/opt/novell/grpwise ”by default.

If you want to repeat the creation of the TA or if there is already a TA named GWEMACON, you can accept this by checking the ”Overwrite” checkbox.

With a click on Generate Key you create the TA together with the key.

Click on ‘Save to file’ to store the key in a file. This file will be the foundation for the Postoffice configuration files for GWEMACON later.

3.2.3  Ckecking the TA

In the next step you should check the Trusted Application with ConsoleOne and activate the retention mechanism.

Open ConsoleOne with the GroupWse Plugin (the same way you use it to administer your GroupWise System). The screenshots have been made with ConsoleOne on Linux.

First you should check, whether the TA has been created correctly. Open with Tools | GroupWise System Operations | Trusted Applications the overview of the configured TA.

In that list, you should find GWEMACON.

Chose GWEMACON and click on ‘Edit’. You should now see the lower window. Check for the checkmark in front of ‘Provides Message Retention Service’.

When this is OK, you can close both windows by clicking on ‘Cancel’ resp. ‘Close’.

3.2.4  Configuring the Postoffice for Retention

Next, you should activate the retention feature for all postoffices, that will be archived. Without this setting, GWEMACON can read and archive messages, but the user (or one of his rules) could delete and empty messages before the connector had a chance to see them.

This settings have to be set for each postoffice, that should be archived.

Select the postoffice in the left pane under ‘GroupWise System’. Now chose Tools | GroupWise Utilities | Client Options on the menu bar of ConsoleOne.

In ‘Client Options’, chose ‘Environment’.

Now select the ‘retention’ tab. The most important setting is the ‘Enable Message Retention Service’ Checkbox. This has to be checked for a reliable Message archiving.

Repeat this step for all postoffices that need to be archived with GWEMACON

Attention: If this checkbox is checked, users are not able to empty messages that are younger than the timestamp of the last run of GWEMACON. When a message is deleted, it will be moved to the trash folder, but it cannot be removed or emptied from there before the timestamp has been advanced.

So don not activate this checkbox for postoffices that should not be archived.

3.2.5  Configuring the Postoffice for SOAP and IMAP

To allow the connector access to postoffice, SOAP and IMAP have to be enabled on the POA (Post Office Agent). Thes settinge have also to be done for each postoffice that should be archived.

In ConsoleOne select the Postoffice in the left pane. In the drop.down list over the right pane, select ‘Post Office Agents’.

Now double click on the POA. On the first tab under GroupWise, select ‘Agent Settings’.

Make sure, that ‘Enable IMAP’ and ‘Enable SOAP’ are checked. The number of threads can stay at the default. GWEMACON works ‘in order’, that means, it uses only one thread.

Now select GroupWise | Network Address.

Check and write down the assigned IP Address and the Ports for SOAP and IMAP. GWEMACON is also able to use SSL, if the OpenSSL libraries are installed.

If more than one POA is running on the same server, you have to assign unique Ports for each POA.

3.3  Configuring the Connector

For an easy and convenient configuration of the connector you will need an Windows Workstation again. The configuration program doesn’t need any installation. You simply start ‘’settings.exe” from /opt/gwema/win or from the extracted archive.

For each postoffice to archive, GWEMACON needs a configuration file in /opt/gwema/conf. The start/stop script will start an connector process for each of those config files. These files have by convention the name of the postoffice, followed by ‘.conf’. The ending is needed, because the script looks only for files ending with ‘.conf’.

Starting point for a configuration file is the key file you created in 3.2.2.

When starting settings the following window appears:

Click ‘Read Keyfile’ behind ‘Trusted Application Name’. A file open dialog appears where you can select the keyfile. You can also select another configuration file, only the key data will be extracted from it. Now we have to fill the other fields:

• PO Name: Enter the name of your GroupWise Postoffice. This name will be used for logging only.
• POA Address: The IP-Address of the Postoffice Agent (see 3.2.5)
• SOAP-Port POA: The Port number of the POA for SOAP. When you click ‘Default’ 7191 will be set.
• IMAP-Address POA: Also the IP Address of POA. If IMAP is activated on GWIA, you can enter this Address there. GWIA will route the requests to POA.
• IMAP-Port POA: The Port number of IMAP on the POA. Clicking on ‘Default’ enters 143, the default port for IMAP.
• EMA Address: The IP Address of your EMA.
• Trusted Application Name: Default is GWEMACON, read from the keyfile.
• Trusted Application Key: Lots of hex numbers, is also read from the keyfile.

• Main Domainname: this is the name of the primary internet domain, which is associated to the postoffice. You have to configure this name in EMA, too.

The following screenshot shows an example:

The next tab to configure is ‘Control’:

• Loglevel: This value (0 to 3) sets the verbosity level for the log entrys. You’ll find the log messages in ”/var/log/mail”.
• Error eMail Address: This is to eMail Address GWEMACON can send severe errors to.
• SMTP Host: the host the error messages will be sent to. Usually this is the IP-address of GWIA. If you leave this two fields blank, nothing will be sent.
• HTTP Port: this is the Port, the build-in Webserver listens for requests. Default is 7007. If you have multiple connectors (postoffice connections) running on your server, these ports have to be unique.
• HTTP Username, HTTP Password: this is the username/password combination for authentication to the Webserver. Default is admin/admin.

At the options tab you can configure, whether Appointments, Notes, Jobs and Phone Messages will be archived. Here you will also find the setting for Junkmail.

On the right side you find the waiting time bedween 2 archiving cycles. This is the time, the connector process sleeps between two runs through all the mailboxes of the postoffice.

When all settings are done, save the config file by clicking ‘Save’. Use the postoffice name for the filename with the extension ‘conf’. The whole name should contain only one dot – the one before conf.

Now transfer the configuration file to /opt/gwema/conf.

3.4  Activating and Starting of GWEMACON

When all postoffice connections have been configured, the connector can be activated and started. You will need a terminal window logged in as root on the GWEMACON server.

3.4.1.1  Activating the ControlScript

The statement

server:~ # chkconfig bond-gwemad 35

activates GWEMACON. It will be started when the system starts next time. Alternatively you can use YAST -> Runlevel Editor on the GUI. To start GWEMACON now, use the following command:

3.4.1.2  Manual starting and stopping

With the command

server:~ # rcbond-gwemad action

the following actions can be done:

• start: All configured postoffice connections will be started, if they are not already running.
• stop: All configured postoffice conncetions will be terminated. The processes terminate after finishing the current cycle.
• status: Show the status of all configured connections.
• restart: All connections will be stopped and started again.
• reload: All running connections get a signal, to re-read their configuration.

3.4.1.3  Controlling Connections seperately

If you need to control one connection process for maintainance or debugging you can use

server:~ # /opt/gwema/bin/gwema action config

config is the name of the configuration file or the postoffice (without the extension .conf).

The acitons you can use are the same as under ‘Manual starting and stopping‘. Actually, rcbond-gwemad just calls this script for all configured connections.

It is also possible to send signals (with kill) to the running connector processes. They behave as they should – TERM terminates the Process (after the current cycle), HUP causes the re-read of the configuration.

3.5  Modifying the configuration manually

Sometimes it may be more convenient to edit the configuration files ‘by hand’. These files are quite simple: they are pure text files. Each line contains a keyword, an equal sign and the value. Each keyword corresponds to one input field of the setting program.

Keyword	Input field	Value
PONAME	PO Name	String
POAADDR	POA Address	IP-Address
POASOAP	SOAP-Port POA	Number
POAIMAPADDR	IMAP-Address POA	IP-Address
POAIMAP	IMAP-Port POA	Number
EMAADDR	EMA Address	IP-Address
TANAME	Trusted Application Name	GWEMACON
TAKEY	Trusted Application Key	64 digits hex-number
DOMAINNAME	Main Domainname	String
LOGLEVEL	LogLevel	0<=Number<=3
SYSADMIN	Error eMail Address	String
SMTPHOST	SMTP Host	IP-Address or Name
HTTPPORT	HTTP Port	Number
HTTPNAME	HTTP Username	String
HTTPPWD	HTTP Password	String
SLEEPTIME	Time between 2 Syncs	Number
ARAPP	Appointments	true/false
ARNOTE	Notes	true/false
ARJOB	Jobs	true/false
ARPHONE	Phone Messages	true/false
ARJUNK	Junkmail	true/false

The .”key” files, that are created by GWEMTA contain only the two lines TANAME and TAKEY.

4  Licensing

GWEMACON runs without any restrictions with every EMA, that runs in ‘Try and Buy’ mode. This allows all neccesary test at the customes site.

As soon as the appliance gets licensed, you will need an license file for GWEMACON.

You’ll get the license file by eMail.

The name of the file is the serial number of your EMA with the extension .lic. The content of the file is the license code as a 16 to 20 digit hex number. So this file is quite small.

4.1  Installing the license

Just copy the license file to ”/opt/gwema/bin” and (re-)start the connector using

server:~ # rcbond-gwemad restart

5  Additional License and Copyright Informations

GWEMACON was developed with Free Pascal/Lazarus. The compiler and the IDE are OpenSource Software under GNU Public License (GPL). Both can be downloaded at www.freepascal.org. The runtime libraries, that are linked in GWEMACON is licensed using the LGPL (lesser or library GPL). The sources of the runtime library can also be dowmloaded from www.freepascal.org.

For communication, GWEMACON uses a library named Ararat Synapse. The homepage of Synapse is www.ararat.cz/synapse, where you can find the sources. Following the license terms of this library we have to include the following statement in our documentation:

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. Neither the name of Lukas Gebauer nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

You can find more informations about Open Source and licenses like LGPL and GPL at www.fsf.org.