EMG 5.2.19 - User's Guide

3. Installing or upgrading EMG

EMG installation/upgrade process includes several steps:

· Download software

· Get license key

· Install software

· Configure software

· Start server

When upgrading from EMG 3 to EMG 5, EMG 5 will read all EMG 3 files from disk and migrate them into the EMG 5 message store automatically.

3.1 Before installing EMG

We recommend starting out by applying relevant patches to your operating system. This particularly applies to Sun Solaris. We recommend applying Sun's most current Recommended Patch Clusters for your Solaris version. Sun patches are available from http://sunsolve.sun.com.

To list installed patches in Solaris use "showrev -p".

3.2 Download software

Software can be downloaded from http://www.nordicmessaging.se/.

You can choose either to download a full distribution or a binaries-only distribution. When installing EMG for the first time you need to download the full distribution. However, when upgrading the binaries-only distribution is enough unless you want new versions of the configuration files. New configuration files are not necessary since EMG is backwards compatible with earlier releases.

3.3 Get license key

Contact your distributor or Nordic Messaging Technologies in order to get your evaluation license key or to purchase a permanent license.

When upgrading from earlier versions of EMG you need a new license key. Contact your reseller or e-mail support@infoflexconnect.se for more information on how to obtain a new license key.

3.4 Install software

3.4.1 Full distribution

Extract the components under the "/tmp" directory. This will create a directory, "/tmp/emg-dist", change to the new directory and execute the install script. The install script will ask a number of questions regarding your configuration and prompt you for the the license key.

# cd /tmp
# gzip -d emg500-21394-solaris-full.tar.gz
# tar xvf emg500-21394-solaris-full.tar
# cd /tmp/emg-dist
# sh ./INSTALL

During the installation you will be able to choose a directory for the configuration files. By default this directory is /etc/emg and will be referred to as EMGDIR in this documentation. If you choose to install the software using another directory for the configuration files, the environment variable EMGDIR needs to be set correspondingly in order for the programs to find the configuration files.

Example for setting the EMGDIR variable to an alternate directory, /opt/emg/etc, in Bourne shell or equivalent:

# export EMGDIR
# EMGDIR=/opt/emg/etc

After running the installation you should be able to execute "emgd -v" in order to display your license information.

Sample output from an INSTALL script session on Solaris:

# sh ./INSTALL

* * *  Enterprise Messaging Gateway 5.2.0 - INSTALLATION  * * *

EMG can be owned by the user root or by another user.
What user should be the owner of the EMG files? [root]
What group should be the group for the EMG files? [root]
Where should Enterprise Messaging Gateway configuration
configuration files go? [/etc/emg]
Where should EMG executables go? [/usr/bin]

* * *  Make sure this directory is in your PATH!  * * *
Creating directories...OK
Moving programs...OK
Moving data files...OK
Creating configuration file...OK
LICENSE INFORMATION
Enter your license information EXACTLY as received.
HOSTID     :
COMPANY    : DEMO
TELNO      : 123456
SERIAL     : emgDEMO
LICENSEDATA: 30/May/2010-30/May/2010-10-0-1
ACTIVATION : D8055F1BC5119EFB79B51C378CF01E6292CCCA6D

By creating /etc/init.d/emg the Enterprise Messaging Gateway server
can be automatically started on system boot.
Should the server be automatically started on system boot? [y]

Creating /etc/init.d/emg.
Linking /etc/init.d/emg to /etc/rc2.d/S99emg.

INSTALLATION FINISHED!
======================

The configuration file is placed in /etc/emg and named server.cfg.
The EMG server, emgd, can be started with "emgd".

Check the file /etc/emg/README for more information.

3.4.2 Binaries-only

The easiest way to upgrade an existing EMG software installation is to use the binaries-only distribution. Since EMG is backwards compatible with earlier versions no configuration changes should be needed unless new functionality needs to be accessed.

The upgrade procedure is as follows:

Log on to your system as the system administrator or the EMG user.

Find your current EMG binaries, for example emgd. They are usually located in /usr/bin. You can also execute "type emgd", which will locate the binary if it is in your current path.

Download the patch release tar-archive, in this example we use emg25-solaris-binaries.tar.gz, and save it in the file system under /tmp or similar.

Uncompress the archive:

gzip -d /tmp/emg520-21394-solaris-binaries.tar.gz

Stop emgd, "emgd -stop", and then make sure there are no emgd processes running, "ps -ef | grep emgd". All emgd processes need to be stopped before replacing the binaries.

Backup your current binaries in order to be able to revert to these files if needed. Sample backup procedure:

mkdir /tmp/emg-backup.100530/
cp /usr/bin/emg* /tmp/emg-backup.100530/

Extract the new binaries:

cd /usr/bin
tar xvf /tmp/emg520-21394-solaris-binaries.tar

Make sure they have appropriate owner and permissions (we use root in this example):

chown root /usr/bin/emg*
chmod 555 /usr/bin/emg*
chmod 500 /usr/bin/emgd

Verify that the new binaries execute ok (the command below should not give any error messages):

emgd -help

Verify that the server configuration is ok (if not, make required adjustments):

emgd -verify

Start the server:

emgd

Verify that the server is running:

ps -ef|grep emgd

You should now be up and running with your upgraded software.

3.5 Configure software

Configuring the software usually involves

· Creating a server.cfg that includes configuration for the needed connectors.

· Creating a client.cfg with hostname, port and possibly authentication information for MGP clients.

After the installation there will be a sample configuration in EMGDIR.

3.6 Starting, stopping and refreshing the server

The server can be started by simply running

# emgd

It is possible to set the debug level to DEBUG using the "-debug" option. It will also send the debug output to stdout.

# emgd -debug

The server can be stopped using

# emgd -stop

To refresh the server use

# emgd -refresh

There are 3 different ways to refresh the server:

1 Run "emgd -refresh" (active connections are reset)

2 Run "emgd -reload" (active connections are not affected)

3 Use emgclient or another MGP client (requires MGP administrator privilege)

Reloading the server is done by running "emgd -reload".

3.7 On-disk message store

In EMG 5 all EMG queues are stored on disk in an embedded database.

The indexed files of the database are located in the EMG spool directory.

Do not try to modify these files manually since you will most likely end up with a corrupted database.

Files in SPOOLDIR:

dlr.hdb Delivery reports
kwsession.hdb Keyword sessions
qe.hdb Messages
sat.hdb SAT entries
seqno Message sequence number (id)

The indexed files of the database are located in the EMG spool directory.

It is possible to export the contents of the database using "emgd -exportxml".