Installing EMG 7 and EMG Portal 3 on CentOS 7

The instructions below applies to EMG 7.0, 7.1, and 7.2.

This document describes the steps involved to install a complete EMG platform with

running in CentOS 7.2.1511, released in December 2015 (end of support, June 30, 2024).

CentOS 7 provides

Apache 2.4.6
PHP 5.4.16
MariaDB (MySQL) 5.5.44

through the default yum repositories which meet the EMG Portal requirements well. Other Linux distributions and later versions of these tools often work fine. However, EMG Portal currently does not work on CentOS 8. If you are installing EMG Portal on a system using PHP 7, replace emgportal-eval.php with emgportal-eval-7.php. Please note that PHP 8.0 and higher is not yet supported. The MySQL version must be at most 8.3.

We will install on Centos 7 (64-bit), create a separate user for emg and place the EMG installation in /home/emg. This will give us a privilege-separated installation in its own location.

Basic OS installation and configuration

Download and install CentOS 7.2.1511 (64-bit). We choose the “minimal” distribution,
http://ftp.lysator.liu.se/pub/CentOS/7.2.1511/isos/x86_64/CentOS-7-x86_64-Minimal-1511.iso
After installation, login as “root”
Consider disabling SELinux, at least during the installation.
We recommend that you do not use Plesk on this server, as this conflicts both with the firewall commands and the installation of EMG Portal.
Consider disabling ipv6 if you will not use it:
https://wiki.centos.org/FAQ/CentOS7#head-8984faf811faccca74c7bcdd74de7467f2fcd8ee
Modify Postfix configuration to use ipv4 only. In /etc/postfix/main.cf change the line
```
inet_protocols = all
```
to
```
inet_protocols = ipv4
```
and restart Postfix by running
```
systemctl restart postfix
```
Run a “yum update” to ensure all packages are up to date. If any kernel packages were updated, please reboot the server.
```
yum update -y
reboot
```

Install some additional required and useful packages.

yum install -y bzip2 httpd httpd-devel mod_ssl mariadb-server mariadb-devel php php-pdo php-mysql php-pear php-xml php-mbstring php-devel pcre-devel gcc mlocate mailx net-tools vim-enhanced wgetsystemctl enable mariadb
systemctl enable httpd
systemctl enable postfix

Create user “emg” and assign a good password to the new account. Consider having a strong password generated by your favourite password manager.
```
useradd -m emg
passwd emg
```
Consider limiting ssh access to specific users by adding “AllowUsers emg” to /etc/ssh/sshd_config
```
vi /etc/ssh/sshd_config
systemctl restart sshd
```

Consider synchronizing server time with NTP servers

yum install -y ntpdate ntp
ntpdate 0.pool.ntp.org
systemctl enable ntpd
systemctl start ntpd

Tune some InnoDB and query parameters for MySQL. Change “[server]” section in “/etc/my.cnf.d/server.cnf”.

vi /etc/my.cnf.d/server.cnf

[server]
innodb_additional_mem_pool_size = 128M
innodb_buffer_pool_instances = 2
innodb_file_per_table
innodb_flush_log_at_trx_commit = 2
query_cache_limit = 16M
query_cache_size = 128M

Start services and secure the mysql installation by setting a root password etc
```
systemctl start postfix
systemctl start mariadb
mysql_secure_installation
```
Set the default timezone in php.ini. In the distributed php.ini there is a line “date.timezone =” which should be replace with “date.timezone = ‘Europe/Stockholm'” or whichever timezone is correct for you, check http://php.net/manual/en/timezones.php for more information. Also consider increasing limits for memory usage and execution time.
```
vi /etc/php.ini

date.timezone = 'Europe/Stockholm'
memory_limit = 512M
max_execution_time = 600
```

EMG installation

We are now ready to install and configure EMG.

Request an eval license key at https://nordicmessaging.se/request-evaluation-license/
Login as “root”.
Download the latest EMG 7 (Linux 64-bit) “Full distribution” at https://nordicmessaging.se/about-emg/downloads using download username / password from the eval license key email. In the commands below, please update the URL and file name to match the version you want to download.

cd /tmp
wget --http-user=... --http-password=... \
https://nordicmessaging.se/wp-content/uploads/binaries/emg72/emg...tar.gz
tar xvzf emg...tar.gz
cd emg-dist
sh ./INSTALL

Specify the newly created user “emg” for user and group, “/home/emg/etc” for configuration files, “/home/emg/bin” for executables plus your eval license information.
Add “export EMGDIR=$HOME/etc” to the end of bash profile script.
```
echo 'export EMGDIR=$HOME/etc' >>/home/emg/.bash_profile
```
Login as “emg”.
Replace the default EMG configuration file with the EMG dbconfig configuration file.
```
cp /home/emg/etc/server.cfg.dbconfig /home/emg/etc/server.cfg
```

Create the EMG database and schema, but first edit the script to set a secure password, preferably one that is generated by a password manager application.

cd /home/emg/etc/sql
vi ./createemgdb-mysql.sh
sh ./createemgdb-mysql.sh createdb
sh ./createemgdb-mysql.sh createtables
sh ./createemgdb-mysql.sh initdbconfig

Edit the server.cfg file, and change the database credentials to match the above in the DATABASE section.
```
vi /home/emg/etc/server.cfg
```

EMG perl installation

In order for the EMG Portal billing plugin (and EMG perl plugins in general) to work properly the EMG perl distribution needs to be installed. More information here: https://nordicmessaging.se/emg-5-2-6-and-perl-plugins/.

Please note that this will be a perl installation completely separated from the default perl installation used by /usr/bin/perl. To install modules and run the EMG perl distribution you must run the perl binary with the full path (/opt/perl-5.12.2-emg/bin/perl) and always as user “emg” to avoid mixing up file permissions. However, below we add the new perl bin directory first in the PATH for the “emg” user in order to ensure the EMG perl binary is always used when using “emg” account.

Download and extract EMG perl distribution as user “root”

cd /opt
wget https://nordicmessaging.se/wp-content/uploads/binaries/perl-5.12.2-emg_linux_64bit.tar.gz
tar xvzf perl-5.12.2-emg_linux_64bit.tar.gz
chown -R emg.emg perl-5.12.2-emg
su - emg
echo 'export PATH=/opt/perl-5.12.2-emg/bin:$PATH' >>$HOME/.bash_profile

Install some required CPAN modules. When running the cpan command the first time you need to hit enter a couple of times to accept the configuration. We run cpan twice, first to update the cpan command itself, and then to install the modules we need.

PERL_MM_USE_DEFAULT=1 /opt/perl-5.12.2-emg/bin/cpan -f CPAN
PERL_MM_USE_DEFAULT=1 /opt/perl-5.12.2-emg/bin/cpan -f PEVANS/IO-Socket-IP-0.41.tar.gz CJM/IO-HTML-1.001.tar.gz DVEEDEN/DBD-mysql-4.052.tar.gz Carp::Assert DBI Data::Dumper Email::Sender::Simple Email::Sender::Transport::SMTP Email::Simple Email::Simple::Creator Encode Filesys::Df HTTP::Daemon HTTP::Status JSON LWP MSOUTH/IPC-Shareable-0.61.tar.gz Net::Subnet Time::Hires RI::QueryParam

EMG watchdog installation

The EMG watchdog can monitor the EMG server process (emgd) and perform operations such as stopping server, starting server and retrieve EMG server log files to EMG Portal. It also monitors available disk space in the file system and sends a notification when a specified limit has been reached.

It features a built-in web server used to serve the API calls. The web server listens on port 3000 by default.

Log out, and then log in as “emg”. This is required to get the new value of the $PATH variable.

Copy the sample watchdog script

cp /home/emg/bin/emg_watchdog.pl.sample /home/emg/bin/emg_watchdog.pl

Go through the “Configuration variables” section in the watchdog script and add any variables you want to change to a new file “emg_watchdog.cfg”.
More specifically make sure the following are set to relevant values:

@notify_recipients – E-mail address(es) to which watchdog should send e-mail notifications
$mail_from – Sender address (“From”) for e-mail notifications
$smtp_server

Sample string to add new values for @notify_recipients and $mail_from to emg_watchdog.cfg:
```
echo -e "@notify_recipients = ('recipient@example.com');\n\$mail_from = 'changeme_from@example.com';" >$HOME/bin/emg_watchdog.cfg
```

EMG Portal installation

Time to download and install EMG Portal. The evaluation version of EMG Portal is encoded with ionCube and first an ionCube loader must be configured in PHP.

As user “root”, configure the firewall to allow https (port 443) and optionally http (port 80) connections in the firewall and start the httpd service. We recommend using https only since communication will then be protected by TLS encryption. However, if you use the default self-signed TLS certificate the visting browser will throw a warning when accessing the page. Installation of a proper certificate signed by a trusted CA is therefore strongly recommended.
```
systemctl start firewalld
firewall-cmd --zone=public --add-port=80/tcp --permanent # Optional - not recommended
firewall-cmd --zone=public --add-port=443/tcp --permanent
firewall-cmd --reload
systemctl start httpd
```

Download the ionCube loader wizard from https://ioncube.com/loaders.php and install it by placing the installer wizard in /var/www/html and point your browser to https://servername/ioncube/loader-wizard.php. Follow the instructions and remember to delete the loader files in web directory after completing the loader installation. Run “php -version” to get your PHP version, and replace “5.4” in the file name below with your version. If there is no matching ioncube version, for example for version 8.0, please upgrade or downgrade to one of the supported versions. As mentioned, PHP 8.0 and higher is not yet supported.

cd /var/www/html
wget https://www.ioncube.com/loader-wizard/loader-wizard.tgz
tar xvzf loader-wizard.tgz
[ Open browser and follow instructions, which should correspond to commands below ]
cd /usr/lib64/php/modules/
wget https://downloads.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.tar.gz
tar xvzf ioncube_loaders_lin_x86-64.tar.gz
echo "zend_extension = /usr/lib64/php/modules/ioncube/ioncube_loader_lin_5.4.so" >/etc/php.d/20-ioncube.ini
systemctl restart httpd
[ The ionCube loader should now load properly if you point your browser to
https://servername/ioncube/loader-wizard.php?timeout=0&ini=0&page=loader_check ]
rm -rf /usr/lib64/php/modules/ioncube/ /var/www/html/loader-wizard.tgz /var/www/html/ioncube/

Download the current 30-day eval as user “root”. If you are using PHP 7, replace emgportal-eval.php with emgportal-eval-7.php. As mentioned, PHP 8.0 and higher is not yet supported.

cd /tmp
wget -O emgportal.tgz https://nordicmessaging.se/wp-content/uploads/emgportal-eval.php
cd /var/www/html
mkdir emgportal
cd emgportal
tar xvzf /tmp/emgportal.tgz
chown -R emg.emg /var/www/html/emgportal
chmod 777 assets protected/runtime
chmod 777 protected/config
cp htaccess.sample .htaccess

Modify .htaccess to use the right sub-uri by uncommenting “#RewriteBase /emgportal”
```
vi .htaccess
```
Configure apache by copying emgportal.conf to the apache config directory and restart the httpd service.
```
cp /var/www/html/emgportal/emgportal.conf /etc/httpd/conf.d
systemctl restart httpd
```
If you access the EMG Portal installer from a remote computer you will need to add your IP address to AUTHORIZED_IPS variable on line 3 in the installer file.
```
vi /var/www/html/emgportal/install/index.php
```
Copy protected/config/main.php.sample to protected/config/main.php.
Now you should be able to point your browser to your server https://yourserver/emgportal and see the EMG Portal installer.

After finishing the installer you need to remove installation directory and secure config files

cd /var/www/html/emgportal
rm -rf install/
chown -R emg.emg /var/www/html/emgportal
chmod 755 protected/config

As a final step you should check the main config file for any settings you want to customize especially the “baseUrl”, “adminEmail” and “emailReportCopy” settings. You can also define your own layout file and point to it through the “layout” setting.
```
vi /var/www/html/emgportal/protected/config/main.php
```
You should now be able to log in to EMG Portal as the web user you specified during installation.

Finish EMG installation

You need to copy the billing plugin from EMG Portal distribution into the EMG etc directory.

Copy the billing.pl file as the “emg” user and update the database credentials in the file. Also copy and update the mo_routing.pl file in the same way.
```
su - emg
cp /var/www/html/emgportal/misc/billing.pl /home/emg/etc/
vi /home/emg/etc/billing.pl
```
As user “root”, open the firewall for incoming SMPP connections. In server.cfg there is an incoming SMPP connector listening on port 2775, but we have yet to allow inbound connections on that port
```
firewall-cmd --zone=public --add-port=2775/tcp --permanent
firewall-cmd --reload
```
Finally you should be able to start the EMG server by running command “emgd” as the user “emg”. The command “emgstat” should give you a list of connectors in the EMG server and their status. Please examine the $EMGDIR/log/general file, and fix any errors or warnings.
You should now be able to login to the EMG Portal and see the same information under “Dashboard -> Connectors”.
As the “emg” user, start the EMG watchdog by running the command below. You should receive an e-mail notification when the watch has started if all went ok.
```
/home/emg/bin/emg_watchdog.pl &
```
In EMG Portal under “Dashboard” -> “System settings” on the bottom of the page under “EMG Server(s)”, add “3000” as the “Watchdog port” on the first line and save.
You should now see “EMG watchdog: Enabled – Running” on the “Dashboard”.

echo 'su - emg -c "perl /home/emg/bin/emg_watchdog.pl &"' >>/etc/rc.local
chmod 744 /etc/rc.local

Recurring tasks (cron)

A few cron jobs need to be added to enable recurring tasks.

There is a sample script “cleandb.sh.sample” in the /home/emg/bin directory. The “hourly_summary.pl.sample” script is part of the EMG Portal distribution.

As user “emg”, copy them and review paths and database settings in the scripts to ensure they run correctly.

cp /home/emg/bin/cleandb.sh.sample /home/emg/bin/cleandb.sh
cp /var/www/html/emgportal/misc/hourly_summary.pl.sample /home/emg/bin/hourly_summary.pl
cp /var/www/html/emgportal/misc/hourly_summary_connector.pl.sample /home/emg/bin/hourly_summary_connector.pl
vi /home/emg/bin/cleandb.sh
vi /home/emg/bin/hourly_summary.pl

Then add crontab entries similar to extract below.

crontab -u emg -e (if running as user "root")
crontab -e (if running as user "emg")

Extract from “crontab -l -u emg” on a running server:

# Purge old records from EMG database
*/5 * * * * /home/emg/bin/cleandb.sh >>/tmp/cleandb.log 2>&1
# Aggregate statistics for EMG Portal message reports
* * * * * /home/emg/bin/hourly_summary.pl >>/tmp/hourly_summary.log 2>&1
* * * * * /home/emg/bin/hourly_summary_connector.pl >>/tmp/hourly_summary_connector.log 2>&1
# Trigger daily report for current month
5 0 * * * wget --no-check-certificate -O - https://127.0.0.1/emgportal/cron/reportMonth >/tmp/cron_report.log 2>&1
# Trigger scheduled jobs
* * * * * wget --no-check-certificate -O - https://127.0.0.1/emgportal/cron/sendScheduled >/tmp/cron_send.log 2>&1

What’s next?

You should now have a running messaging solution with server and web interface for provisioning tasks.

When using the command-line, remember to always run commands as user “emg”, or file permissions may be incorrectly set.

Next steps include:

Set up routing (we recommend adding a default route).
Set up pricing (we recommend adding a default price).
Provision customer accounts.
Remember to open the port in the firewall if you add new inbound connectors.
Consider adding a proper SSL certificate to protect your site and for increased customer trust.
Create automatic backups of the database.
Version control (we recommend git) and backup the EMG configuration files.

Please consult the EMG Portal documentation for some more information about EMG Portal functionality.