EMG 3.1.5 - User's Guide

Table of ContentsPreviousNextIndex

3. Installing or upgrading EMG

EMG installation/upgrade process includes several steps:

Download software
Get license key
Install software
Configure software
Start server

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/download.

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 (EMG 1, 2 or 2.5) you need a new license key. If there is an active support agreement in place for your license you can get the new license key by sending e-mail support@infoflexconnect.se requesting the new key. Include the current license key in the e-mail. Delivery time for licenses may be up to two workdays.

3.4 Install software

3.4.1 Full distribution

Extract the components under the root directory. This will create a directory, /tmp/emg2, 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 /
# gzip -d emg30-solaris-full.tar.gz
# tar xvf emg30-solaris-full.tar
# cd /tmp/emg
# 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 2.5 - 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
Enter your license information EXACTLY as received.
HOSTID     : 
TELNO      : 123456
SERIAL     : emgDEMO
LICENSEDATA: 30/Aug/2003-0-0-1

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.


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/emg30-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.020501
cp /usr/bin/emg* /tmp/emg-backup.041030

Extract the new binaries:

cd /usr/bin
tar xvf /tmp/emg30-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:


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"
2 Run "kill -1 <pid>" where pid is the parent emgd process
3 Use emgclient or another MGP client (requires MGP administrator privilege)

EMG 3 also supports reloading which is similar to refresh with the difference that open sessions are not closed as is the case during a refresh.

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

3.7 Persistence

When the server is stopped the connector messages queues and the routing log are flushed to disk. The entries will be stored in the files queues.dat and routelog.dat respectively. The format of these files is one MGP option key-value pair per row with an extra empty line as message separator.

If message persistence is enabled in the license flush files are not used. Instead all messages, DLRs and SAT entries are stored in the file system immediately upon reception and for the whole message life cycle. When the message has reached its final status (delivered or failed) it is also removed from disk. This way no messages will ever be lost even if the server terminates unexpectedly or crashes.

Table of ContentsPreviousNextIndex