EMG 3.1.5 - User's Guide
3. Installing or upgrading EMG
EMG installation/upgrade process includes several steps:
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 email@example.com 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
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! * * *
Moving data files...OK
Creating configuration file...OK
Enter your license information EXACTLY as received.
COMPANY : DEMO
TELNO : 123456
SERIAL : emgDEMO
ACTIVATION : I-6l5H94FafYn4A6
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]
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.
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:
cp /usr/bin/emg* /tmp/emg-backup.041030
Extract the new binaries:
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):
Verify that the server configuration is ok (if not, make required adjustments):
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
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
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:
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".
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.