PlaySMS Kannel SMS Gateway integration on NGINX+Debian

This post is about PlaySMS Kannel SMS Gateway integration on NGINX+Debian

PlaySMS:

PlaySMS is a free and open source SMS management software, a web interface for SMS gateways and bulk SMS services. In this article we will configure PlaySMS on Debian 10 with NGINX web server and MariaDB Database. We will need PHP to run PlaySMS web application and Kannel SMS Gateway. To install Kannel SMS Gateway please check this article.

LAB Environment Host Info:

PlaySMS and Kannel Server Host IP: 192.168.10.38
Client Host IP: 192.168.10.31

Installing NGINX:

We will use prebuilt Debian Package from the Official NGINX Repository

Download and add the NGINX packages and the repository signing key to apt program’s key ring:

root@sms-gw:~# wget https://nginx.org/keys/nginx_signing.key
root@sms-gw:~# apt-key add nginx_signing.key

To add NGINX source list, create /etc/apt/sources.list.d/nginx.list file with below contents

deb https://nginx.org/packages/debian/ buster nginx
deb-src https://nginx.org/packages/debian/ buster nginx

Update repository list and install NGINX

root@sms-gw:~# apt-get update
root@sms-gw:~# apt-get install –y nginx

Enable and Start NGINX service and verify that NGINX Server is up and running:

root@sms-gw:~# systemctl enable nginx.service
root@sms-gw:~# systemctl start nginx.service
root@sms-gw:~# netstat –lntp
root@sms-gw:~# curl -l 127.0.0.1

From Client Machine:

NGINX Server is running and showing its default page.

Installing PHP:

Now install PHP, PHP-FPM and other PHP packages required for PlaySMS

root@sms-gw:~# apt-get install –y php php-fpm php-mysql php7.3-mysql php7.3-cli php7.3-common php7.3-xml php7.3-xmlrpc php7.3-mbstring php7.3-gd php7.3-curl

Enable and Start PHP7.3-FPM service and check status

root@sms-gw:~# systemctl enable php7.3-fpm.service
root@sms-gw:~# systemctl start php7.3-fpm.service
root@sms-gw:~# systemctl status php7.3-fpm.service

NGINX Configuration for PlaySMS:

Create /etc/nginx/fastcgi.conf file with below contents using vim

fastcgi_param  SCRIPT_FILENAME    $document_root$fastcgi_script_name;
fastcgi_param  QUERY_STRING       $query_string;
fastcgi_param  REQUEST_METHOD     $request_method;
fastcgi_param  CONTENT_TYPE       $content_type;
fastcgi_param  CONTENT_LENGTH     $content_length;

fastcgi_param  SCRIPT_NAME        $fastcgi_script_name;
fastcgi_param  REQUEST_URI        $request_uri;
fastcgi_param  DOCUMENT_URI       $document_uri;
fastcgi_param  DOCUMENT_ROOT      $document_root;
fastcgi_param  SERVER_PROTOCOL    $server_protocol;
fastcgi_param  REQUEST_SCHEME     $scheme;
fastcgi_param  HTTPS              $https if_not_empty;

fastcgi_param  GATEWAY_INTERFACE  CGI/1.1;
fastcgi_param  SERVER_SOFTWARE    nginx/$nginx_version;

fastcgi_param  REMOTE_ADDR        $remote_addr;
fastcgi_param  REMOTE_PORT        $remote_port;
fastcgi_param  SERVER_ADDR        $server_addr;
fastcgi_param  SERVER_PORT        $server_port;
fastcgi_param  SERVER_NAME        $server_name;

# PHP only, required if PHP was built with --enable-force-cgi-redirect
fastcgi_param  REDIRECT_STATUS    200;

Change www-data user and group to nginx in /etc/php/7.3/fpm/pool.d/www.conf for below config directives

user = www-data
group = www-data
listen.owner = www-data
listen.group = www-data

change to

user = nginx
group = nginx
listen.owner = nginx
listen.group = nginx

root@sms-gw:~# sed -i 's/www-data/nginx/g'  /etc/php/7.3/fpm/pool.d/www.conf

Replace NGINX default config file for PlaySMS to run with FPM/FastCGI

root@sms-gw:~# mv /etc/nginx/conf.d/default.conf /etc/nginx/conf.d/default.conf.bk
root@sms-gw:~# vim /etc/nginx/conf.d/default.conf

Add below lines to /etc/nginx/conf.d/default.conf for PlaySMS

server {
    listen       80;
    root   /usr/share/nginx/html;
    index  index.php index.html index.htm;
    server_name  _;

    access_log  /var/log/nginx/playsms_access.log;
    error_log   /var/log/nginx/playsms_error.log;

    charset utf-8;

    location / {
        try_files $uri $uri/ =404;
    }

    location ~ .php {
        include fastcgi.conf;
        fastcgi_split_path_info ^(.+.php)(/.+)$;
        fastcgi_pass unix:/run/php/php7.3-fpm.sock;
        }

    location ~ /\.ht {
        deny  all;
    }
}

You will need to set your local timezone for PHP.

Uncomment and set date.timezone config directive under [Date] section in /etc/php/7.3/cli/php.ini and /etc/php/7.3/fpm/php.ini to get localtime for your time zone. Example: for New York, USA config would be

date.timezone = America/New_York

Restart the php7.3-fpm service after changing timezone info.

root@sms-gw:~# systemctl restart php7.3-fpm.service

Note: For timezone list please visit: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

Place a test page at NGINX root directory to check PHP configuration with NGINX

root@sms-gw:~# echo "<?php phpinfo(); ?>" > /usr/share/nginx/html/info.php

Browse http://192.168.10.38/info.php from client machine

PHP works properly with NGINX using PHP-FPM socket and showing PHP info.

Install MariaDB:

We will need database service for PlaySMS. Here we are using MariaDB.

Import key for MariaDB in apt key ring

root@sms-gw:~# apt-key adv --fetch-keys 'https://mariadb.org/mariadb_release_signing_key.asc'

Prepare source list for MariaDB: create  /etc/apt/sources.list.d/MariaDB.list file including below lines

# MariaDB 10.3 repository list - created 2021-12-28 18:41 UTC
# https://mariadb.org/download/
deb [arch=amd64,arm64,ppc64el] https://download.nus.edu.sg/mirror/mariadb/repo/10.3/debian buster main
deb-src https://download.nus.edu.sg/mirror/mariadb/repo/10.3/debian buster main

Update repository list and install MariaDB

root@sms-gw:~# apt-get update
root@sms-gw:~# apt-get install –y mariadb-server

If it asks to provide root password for MariaDB, escape it. We will set it later

Enable and Start MariaDB service

root@sms-gw:~# systemctl enable mariadb.service
root@sms-gw:~# systemctl start mariadb.service

Run mysql_secure_installation command to set root password and other security directives as below

Set root password? [Y/n] Y
Set MariaDB root password
Remove anonymous users? [Y/n] Y
Disallow root login remotely? [Y/n] Y
Remove test database and access to it? [Y/n] Y
And finally …
Reload privilege tables now? [Y/n] Y

Create PlaySMS database and user in MariaDB

root@sms-gw:~# mysql -u root –p
MariaDB [(none)]> CREATE DATABASE playsms;
MariaDB [(none)]> CREATE USER 'playsmsuser'@'localhost' IDENTIFIED BY 'playsmsSecuredPassword';
MariaDB [(none)]> GRANT ALL PRIVILEGES ON playsms.* TO 'playsmsuser'@'localhost';
MariaDB [(none)]> FLUSH PRIVILEGES;
MariaDB [(none)]> quit

Now MariaDB is ready for PlaySMS.

Installing PlaySMS:

Install dependencies

root@sms-gw:~# apt-get install -y zip

Add playsms user

root@sms-gw:~# adduser playsms --disabled-password --home=/usr/local/playsms/

Create Log directory and set appropriate permission to it

root@sms-gw:~# mkdir /var/log/playsms
root@sms-gw:~# chown nginx:nginx -R /var/log/playsms

Switch to playsms user

root@sms-gw:~# su - playsms

Download and untar the latest PlaySMS Official release form https://github.com/playsms/playsms/archive/refs/tags/1.4.5.tar.gz

playsms@sms-gw:~$ cd /tmp/
playsms@sms-gw:/tmp$ wget https://github.com/playsms/playsms/archive/refs/tags/1.4.5.tar.gz
playsms@sms-gw:/tmp$ mv 1.4.5.tar.gz playsms-1.4.5.tar.gz
playsms@sms-gw:/tmp$ tar -zxf playsms-1.4.5.tar.gz
playsms@sms-gw:/tmp$ cd playsms-1.4.5/

Note: Do not use PlaySMS version less than 1.4.5, those have security vulnerability which has fixed in version 1.4.5

Create install.conf file with below content

DBUSER="playsmsuser"
DBPASS="playsmsSecuredPassword"
DBNAME="playsms"
DBHOST="localhost"
DBPORT="3306"
WEBSERVERUSER="nginx"
WEBSERVERGROUP="nginx"
PATHSRC="$(pwd)"
PATHWEB="/usr/local/playsms/html"
PATHLIB="/usr/local/playsms/lib"
PATHBIN="/usr/local/playsms/bin"
PATHLOG="/var/log/playsms"
PATHCONF="/usr/local/playsms/etc"

Run install-playsms.sh file to install PlaySMS

Check Installation data and confirm each step

playsms@sms-gw:/tmp/playsms-1.4.5$ ./install-playsms.sh

playSMS Install Script for Ubuntu (Debian based)
==================================================================
WARNING:
- This install script WILL NOT upgrade currently installed playSMS
- This install script WILL REMOVE your current playSMS database
- This install script is compatible ONLY with playSMS version 1.4
- Please BACKUP before proceeding
==================================================================

You are NOT running this installation script as root
That means you need to make sure that this Linux user has
permission to create necessary directories

==================================================================

Proceed ?

When you're ready press [y/Y] or press [Control+C] to cancel Y

==================================================================

INSTALL DATA:

MySQL username      = playsmsuser
MySQL password      = playsmsSecuredPassword
MySQL database      = playsms
MySQL host          = localhost
MySQL port          = 3306

Web server user     = nginx
Web server group    = nginx

playSMS source path = /tmp/playsms-1.4.5

playSMS web path    = /usr/local/playsms/html
playSMS lib path    = /usr/local/playsms/lib
playSMS bin path    = /usr/local/playsms/bin
playSMS log path    = /var/log/playsms

playSMS conf path   = /usr/local/playsms/etc

==================================================================

Please read and confirm INSTALL DATA above

When you're ready press [y/Y] or press [Control+C] to cancel Y

==================================================================

Are you sure ?

Please read and check again the INSTALL DATA above

When you're ready press [y/Y] or press [Control+C] to cancel Y

==================================================================

Installation is in progress

DO NOT press [Control+C] until this script ends

==================================================================

Getting composer from https://getcomposer.com

Please wait while the install script downloading composer

Composer is ready in this folder

Pleas wait while composer getting and updating required packages

Loading composer repositories with package information
Updating dependencies
Nothing to modify in lock file
Installing dependencies from lock file (including require-dev)
Nothing to install, update or remove
Generating autoload files

Composer has been installed and packages has been updated

Start................end

PLAYSMSD_CONF = /usr/local/playsms/etc/playsmsd.conf
PLAYSMS_PATH = /usr/local/playsms/html
PLAYSMS_LIB = /usr/local/playsms/lib
PLAYSMS_BIN = /usr/local/playsms/bin
PLAYSMS_LOG = /var/log/playsms
DAEMON_SLEEP = 1
ERROR_REPORTING = E_ALL ^ (E_NOTICE | E_WARNING)
IS_RUNNING =
PIDS schedule =
PIDS ratesmsd =
PIDS dlrssmsd =
PIDS recvsmsd =
PIDS sendsmsd =

playsmsd has been started
schedule at pid 21444
ratesmsd at pid 21447
dlrssmsd at pid 21450
recvsmsd at pid 21453
sendsmsd at pid 21455

playsmsd is running
schedule at pid 21444
ratesmsd at pid 21447
dlrssmsd at pid 21450
recvsmsd at pid 21453
sendsmsd at pid 21455


playSMS has been installed on your system

Your playSMS daemon script operational guide:

- To start it : playsmsd /usr/local/playsms/etc/playsmsd.conf start
- To stop it  : playsmsd /usr/local/playsms/etc/playsmsd.conf stop
- To check it : playsmsd /usr/local/playsms/etc/playsmsd.conf check

ATTENTION

=========

When message "unable to start playsmsd" occurred above, please check:
1. Possibly theres an issue with composer updates, try to run: "./composer update"
2. Manually run playsmsd, "playsmsd /usr/local/playsms/etc/playsmsd.conf start", and then "playsmsd /usr/local/playsms/etc/playsmsd.conf status"

Exit from playsms user shell

Set proper bin and conf file location in /usr/local/playsms/html/plugin/feature/playsmslog/config.php

$plugin_config['playsmslog']['playsmsd']['bin'] = '/usr/local/playsms/bin/playsmsd';
$plugin_config['playsmslog']['playsmsd']['conf'] = '/usr/local/playsms/etc/playsmsd.conf';

Also need to set proper conf file location in /usr/local/playsms/bin/playsmsd

Change [near about line#222]

$PLAYSMSD_CONF = ”;
To
$PLAYSMSD_CONF = ‘/usr/local/playsms/etc/playsmsd.conf’;

As our web server user/group is nginx, to avoid permission issues we will change the ownership for all contents in PlaySMS web root directory to nginx:nginx

root@sms-gw:~# cd /usr/local/playsms/html/
root@sms-gw:/usr/local/playsms/html# chown nginx:nginx -R ./*

Set new web root directory in /etc/nginx/conf.d/default.conf for PlaySMS

Restart NGINX service

root@sms-gw:~# systemctl restart nginx.service

Browse http://192.168.10.38/ from client workstation and login with default Username: admin, Password: admin

Under My Account > Preferences Menu Change default Password and other information

Integrating PlaySMS with Kannel SMS Gatway:

Go to Setting > Manage Gateway and SMSC in PlaySMS admin web portal, click on the Plus (+) Sign next to kannel Gateway option

Put Kannel Gateway info as we have configured in sendsms-user group in kannel.conf. Ref: Kannel Installation

Note: These info are for bidirectional HTTP API access between Kannel and PlaySMS. As we are installing both service on same server we used localhost for Bearerbox, Send SMS and PlaySMS URL. Please use your host IP Address/FQDN if you install Kannel and PlaySMS on different servers.

The Kannel SMSC will be added under SMSC Tab in Setting > Manage Gateway and SMSC

Go to Setting > Main Configuration. Set Kannel as Default SMSC and save the configuration.

Sending SMS from PlaySMS:

Go to My Account > Compose message, write a SMS and send

Kannel Access log:

Recipient Phone:

Receiving SMS in PlaySMS from Kannel:

To get incoming SMS we will have to add PlaySMS callback URL get-url under sms-service group in kannel.conf file

group = sms-service
get-url = "http://localhost/index.php?app=call&cat=gateway&plugin=kannel&access=geturl&t=%t&q=%q&a=%a&Q=%Q&smsc=kannel"

You will find incoming SMS in Reports > Sandbox in PlaySMS Portal.

From Settings > Route incoming SMS you can set destination/action for an incoming SMS.

Add playsmsd to startup using systemd:

Create systemd unit /etc/systemd/system/playsms.service with below contents

[Unit]
Description=PlaySMS
Documentation=https://playsms.org/documentation/
After=network-online.target 
Wants=network-online.target

[Service]
User=playsms
Type=forking
ExecStart=/usr/local/playsms/bin/playsmsd start
ExecReload=/usr/local/playsms/bin/playsmsd restart
ExecStop=/usr/local/playsms/bin/playsmsd stop
Restart=on-failure

[Install]
WantedBy=multi-user.target

Reload systemd and enable/start playsms.service

root@sms-gw:~# systemctl daemon-reload
root@sms-gw:~# systemctl enable playsms.service
root@sms-gw:~# systemctl start playsms.service
root@sms-gw:~# systemctl status playsms.service

References:

https://playsms.org/documentation/
https://mariadb.org/download/?t=repo-config
https://docs.nginx.com/nginx/admin-guide/installing-nginx/