Installing EMG 8 and EMG Portal

This document describes the steps involved to install a complete EMG platform with EMG 8, EMG Portal, and the EMG Watchdog, running in Ubuntu 24.04 LTS. A few steps are intentionally formulated in a way that forces you to check whether you actually understand what needs to be done (for example, things like “edit the file X”). The reason for this is simple. In order to manage and troubleshoot an EMG server, you need to be comfortable using the Unix command line tools, and understand their output. If you are, going through this guide will be quite trivial. If you are not, please first get assistance from somebody who is.

It may be useful to add the server to your DNS records. Here we will assume that it can be reached using the name emg.example.com.

Basic OS installation and configuration

The EMG binaries are built on Ubuntu 18, and should work on all 64 bit Linux distributions with a libc version of at least 2.27. Some commands and system package names may differ, so pay close attention to any warnings and error messages.

The operating system must be clean, so do not install any management tools such as Plesk.

Login as root.
Update the package lists:
apt-get update
Upgrade the existing packages:
apt-get upgrade -y
Install a few additional packages:
apt-get install -y curl gdb less mariadb-client ntp ntpdate openssh-client valgrind vim zsh
We need PHP 7.4, which requires a few special steps. By default this distribution uses PHP 8.3, which we do not yet support.
- First, we need PHP itself.
  add-apt-repository ppa:ondrej/php -y apt update apt install -y php7.4 libapache2-mod-php7.4 php7.4-mysql php7.4-curl
- Finally, we restart the web server.
  systemctl restart apache2
Make sure the server is using the correct time zone. First find the correct name for your time zone. The Braxo office is in Stockholm, so we would run this:
timedatectl list-timezones | grep Stockholm
This prints Europe/Stockholm. Next, set it:
timedatectl set-timezone Europe/Stockholm
Create the user “emg” and assign a good password to the new account. Consider having a strong password generated by your favourite password manager.
```
useradd -m -s /bin/bash emg
passwd emg
```
Download and install the EMG Perl package. This package includes all CPAN modules used by the plugins used by EMG Portal. If you need additional modules for your own plugins, they must be installed within this environment.
```
cd /tmp
wget https://nordicmessaging.se/wp-content/uploads/binaries/perl-5.40.0-emg.tar.gz
cd /opt
tar xzf /tmp/perl-5.40.0-emg.tar.gz
chown -R emg:emg perl-5.40.0-emg
```

Local email server

The server needs to be able to send emails, so the server needs some sort of local email server. The EMG server can both receive and send emails by itself, so the system email server is just for system messages and status updates from the EMG Watchdog. You can of course configure this system email server any way you want, but a common situation is when you already have an outgoing email server somewhere else. The local email server here could then be installed and configured using the steps below.

Install Postfix:
apt-get install -y postfix
This will start a wizard that will help you with the initial configuration.
If the other email server requires authentication, you need to do a few more things.
- Add the authentication information in the /etc/postfix/sasl_passwd file. It will be a line like this:
  [smtp.example.com]:25 username:password
  The [smtp.example.com]:25 part is what you entered as the relay host and port in the previous step.
- In /etc/postfix/main.cf, add these two lines:
  smtp_sasl_auth_enable = yes smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
  Run
  postmap /etc/postfix/sasl_passwd
Your email server may need additional configuration, which you can add at this point.
Finally, reload the Postfix configuration.
postfix reload

Database server

EMG normally uses a MySQL/MariaDB database for various things. If you already have such a database server up and running, you can skip this section. We will install a new database server on the local machine, as that gives the best performance.

Install the MariaDB server.
apt-get install -y mariadb-server
Check that the database server is running correctly.
systemctl status mariadb
Set the root password, and remove various unused things.
mysql_secure_installation

EMG server installation

Request an evaluation license key at https://nordicmessaging.se/request-evaluation-license/. You will get an email containing the license, as well as the username and password to use when downloading the EMG software.

Download the latest EMG server package to the /tmp directory.

cd /tmp
wget --output-document=emg.tar.gz --http-user=… --http-password=… https://nordicmessaging.se/emg-server-8.php
tar xzf emg.tar.gz

Run the installation script. Specify the newly created user “emg” for user and group, “/home/emg/etc” for configuration files, and “/home/emg/bin” for executables. You can either enter your evaluation license information here, or just leave the fields empty and copy the license data to etc/license manually afterwards. You can answer No on whether to start the server automatically on startup.
```
cd emg-dist
./INSTALL
```

Run “su - emg” to become to emg user. It is very important that all files and directory within the /home/emg directory tree are owned by the emg user, otherwise the EMG server may not be able to start.

Set the EMG base directory in the bash profile script, and make sure you will use the correct perl binaries. If you want to use zsh, do the same for $HOME/.zshenv. Please note the last command, which is not a typo.
```
echo 'export EMGDIR=$HOME/etc' >> $HOME/.bash_profile

echo 'export PATH=/opt/perl-5.40.0-emg/bin:$HOME/bin:$PATH' >> $HOME/.bash_profile

. $HOME/.bash_profile
```
Change the current directory to $EMGDIR. All files and directories from this point, unless they start with a /, are relative to that directory.
Replace the default EMG configuration file with the one to be used with a database based configuration.
```
cp server.cfg.dbconfig server.cfg
```
Create a new password for the database user to be used by EMG. Again, we recommend using a password manager.
Update the sql/createemgdb-mysql.sh script, setting emgpasswd to the new password. Also update the DATABASE section in server.cfg with this information.
Create the EMG database and user. If you decided to disable the root password in the database when running mysql_secure_installation earlier, the command below must be run as the root user.
sh sql/createemgdb-mysql.sh createdb
Edit the server.cfg file, and update the database credentials in the DATABASE section.
At this point we can make a few quick tests to see that the server is working correctly.
- Run
  emgd -v
  to verify that your PATH is correct, and that EMG finds the license information. If not, maybe you forgot to source .bash_profile or .zshrc earlier?
- Create empty versions of the two plugins which will later be provided by the EMG Portal distribution:
  touch billing.pl mo_routing.pl
- Start the EMG server.
  emgd
- Verify that it is running, and has create a couple of connectors.
  emgstat
- Check whether you got any errors or warnings. If so, these must be resolved. There should only be two “CRITICAL” entries, and a few “INFO” entries.
  tail -40 log/general
- You can run
  emgstat -db
  and
  emgstat -plugin
  to see your database connections and plugins, respectively.
- Stop the server, and verify that it takes less than 5 seconds. If not, you may have more information in log/general. This must also be resolved before continuing.
  time emgd -stop
Verify the paths in the with_lock.sh and run_emgd.sh scripts, both in the $HOME/bin directory. Then add a line in the crontab for the emg user, as below. The scripts are described in the release notes for version 8.0.1.
* * * * * /home/emg/bin/with_lock.sh /home/emg/bin/run_emgd.sh
After at most one minute this entry will be run, and you should again be able to run emgstat.

EMG watchdog installation

The EMG watchdog monitors the EMG server process (emgd) and performs operations such as starting and stopping the server. It also monitors the available disk space in the file system and sends a notification when a specified limit has been reached. In order to serve API calls it uses a built-in web server, which listens on port 3000 by default.

Go through the “Configuration variables” section in the watchdog script ~/bin/emg_watchdog.pl and add any variables you want to change to a new file, named ~/bin/emg_watchdog.cfg. In particular, make sure the following ones are set to relevant values.
- @notify_recipients – E-mail address(es) to which the watchdog should send e-mail notifications.
- $mail_from – Sender address for e-mail notifications.
Run ~/bin/emg_watchdog.pl to start the watchdog. It will print a message about being started, as well as sending an email with that message. If you do not receive that email, please check both the configuration above, the watchdog log file etc/log/emg_watchdog.log, the local mail server log at /var/log/mail.log, the logs for the mail server downstreams, any spam filters, etc.
We will now ensure that the EMG watchdog is started automatically on system boot. Previously this was done by updating the /etc/rc.local file, but as of 2025 the support for that mechanism is diminishing. Instead, we will now use the script start_watchdog.sh, which will be included in future versions of EMG.
- If the file $HOME/bin/start_watchdog.sh script does not already exist, create it with this contents.
  !/bin/sh . $HOME/.bash_profile sleep 10 /opt/perl-5.40.0-emg/bin/perl /home/emg/bin/emg_watchdog.pl
  The sleep command is used to wait for the email server Postfix to start. You may need to adjust this value. You can also add “ulimit -c unlimited” before the perl command in order to enable core dumps.
- Run “crontab -e” to edit the crontab of the emg user, and add the following line.
  @reboot /home/emg/bin/start_watchdog.sh

EMG Portal installation

Some files in the EMG Portal application are protected by ionCube, so you need to install their loader. Please note that everything in this section must be done by the root user.

Download the installer.
cd /var/www/html
wget https://www.ioncube.com/loader-wizard/loader-wizard.tgz
tar xzf loader-wizard.tgz
Open the installation wizard, using the correct name of your EMG server. It will tell you what needs to be done. To restart the Apache server, run “systemctl restart apache2“.
http://emg.example.com/ioncube/loader-wizard.php

Next, we install the Portal itself.

cd /var/www/html wget -O /tmp/emgportal.tgz https://nordicmessaging.se/wp-content/uploads/emgportal-eval-7.php mkdir emgportal cd emgportal tar xzf /tmp/emgportal.tgz chown -R emg:emg . chmod 777 assets protected/runtime protected/config cp htaccess.sample .htaccess
Modify the .htaccess file to use the right sub-uri by uncommenting the “#RewriteBase /emgportal” line.
Enable the rewrite module.
a2enmod rewrite
Add the Portal to the Apache configuration.
cp emgportal.conf /etc/apache2/conf-available/ a2enconf emgportal
Restart the web server again.
systemctl restart apache2
Add your IP address, as it would be seen by the EMG Portal, to AUTHORIZED_IPS variable on line 3 in install/index.php. If you are not sure about this value, skip this step for now. The correct value will be printed when starting the Portal installer.
Copy protected/config/main.php.sample to protected/config/main.php. Update the “params” section at the end, most importantly the “baseUrl” field.
Open the EMG Portal installer in your browser, and complete the steps there. Please do not miss the steps on the last page, where you prevent the protected/config directory to be writable by the web server process.
http://emg.example.com/emgportal
The first page shown after logging in to the EMG Portal is the Dashboard. There you should now see a System Information box, showing the version number of both the Portal and the EMG server. It should also show that the Watchdog is running.
We strongly recommend activating HTTPS on the server. The easiest method is most likely to use a free certificate from Let’s Encrypt. Just install and run their tool certbot, according to these instructions from EFF.
To reuse the TLS certificate for incoming connections to EMG, add a cronjob for the root user:
@daily cat /etc/letsencrypt/live/emg.example.com/privkey.pem /etc/letsencrypt/live/emg.example.com/fullchain.pem > /home/emg/etc/emg.pem && chown emg:emg /home/emg/etc/emg.pem
Next, tell EMG about the certificate, by adding this line at the top of the server.cfg file.
SSL_KEYFILE=emg.pem

Finishing touches

Now there are just a few steps left. Here you should again be logged in as the emg user.

Copy the real billing.pl and mo_routing.pl from /var/www/html/emgportal/misc to $EMGDIR, replacing the empty files we created earlier. They both get the database credentials from the configuration, so they should not require any changes.
Copy the helper scripts from /var/www/html/emgportal/misc to $HOME/bin.
cd $HOME/bin cp /var/www/html/emgportal/misc/hourly_summary* . mv hourly_summary.cfg.sample hourly_summary.cfg
Edit hourly_summary.cfg and cleandb.sh and update the database settings. In cleandb.sh you may also want to adjust the other parameters. Later you can include your own tables here, if needed.
Run “crontab -e” to edit the crontab entry for the emg user, and add the following lines:
# Purge old records */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 a daily report for the current month 5 0 * * * wget --no-check-certificate -O - https://emg.example.com/emgportal/cron/reportMonth >/tmp/cron_report.log 2>&1 # Trigger scheduled jobs * * * * * wget --no-check-certificate -O - https://emg.example.com/emgportal/cron/sendScheduled >/tmp/cron_send.log 2>&1

Site specifics

Next up are all your site specific stuff.

In the “Dashboard / EMG configuration / Connectors”, disable the providerA connector, and add your own downstream suppliers. By using virtual connectors such as smpp-out-tmpl you can avoid duplication between connectors with similar options. The “Send” menu option makes it easy to verify their functionality.
Create EMG accounts for the incoming traffic, and then link them to new Customers and Web users. The EMG accounts can connect directly to the EMG server and are used for billing, while Web users can login to the EMG Portal.
Set up routing and pricing. The billing plugin handles routing and pricing for MT messages sent via EMG accounts, and the mo_routing plugin handles routing for MO messages coming back from the SMS providers. So, typically you have the billing plugin enabled on incoming connectors such as smpp-in1, and mo_routing on outgoing connectors such as providerA.
Enable database backups.
Put $EMGDIR under version control, for example using Git. Skip the log and spool directories.
Even though EMG accounts can have their access restricted to specific IP addresses or ranges, having a firewall in front of the server is often a good idea.