Table

of Contents
Introduction 1.1

Installation 1.2
Prerequisite 1.2.1

Ubuntu Setup 1.2.2

Installation Using Install Script 1.2.3

Installation Without Install Script 1.2.4

Upgrades 1.2.5

Version 0.9.9.2 to 1.0 1.2.5.1

Version 1.0 to 1.1 1.2.5.2

Upgrade to Version 1.3.1 1.2.5.3

Version 1.3.1 to 1.4 1.2.5.4
Version 1.4 to 1.4.2 1.2.5.5

Gateway Installation 1.2.6

Kannel 1.2.6.1
Kannel Installation on Ubuntu 1.2.6.1.1

1
Introduction

Introduction
This is a book writing project for playSMS. The project is open to public. Everyone is invited to collaborate and make this
book complete.

The book will include installation and upgrade instruction for playSMS, how to configure playSMS, and how to use and
customize playSMS.

playSMS is a free and open source SMS management software. Example use of playSMS are as follows:

SMS gateway
Bulk SMS provider
Personal messaging system
Corporate and group communication tools

Visit playSMS project website at http://www.playsms.org for playSMS source codes, news and other technical information.

2
Installation

Installation
This chapter is about playSMS installation, upgrades and basic configuration.

3
Prerequisite

Prequisite
playSMS is a web-based software written in PHP and will be using a database server to work with. playSMS requires a
Linux based server and other softwares, products or SMS providers that actually send and receive SMS.

Installing and working with playSMS can be as simple as installing and managing Wordpress or Joomla for example, and
maybe even simpler than those applications.

In order to successfully install and use playSMS one must understand and fullfill some prerequisites.

Below are the list of prerequisite to work with playSMS:

Minimum Hardware Requirements

Hardware requirement:

For hardware you need only a web server capable hardware

Other hardware you need when you have specific plan:

GSM modem, single modem, single port, multiple modems or modem pools with multiple ports
Required only when you plan to use Kannel, Gammu, Gnokii or smstools gateway plugins
Internet connection
Required only when you plan to use Clickatell, Nexmo, Twilio, Infobip, BulkSMS and Uplink gateway plugins
LAN
Required when you plan to link 2 playSMS on different server in the same network using Uplink gateway plugin
Required when you plan to use Kannel and Kannel is on different server in the same network

Minimum Software Requirements

Software requirements:

Operating System Linux

Choose one distro, Ubuntu, Debian, CentOS, or other distro you're familiar with
This book will focus on Ubuntu server
Web server software, for example Apache2, nginx or lighttpd
This book will focus on using Apache2
Database Server MySQL 5.x.x or latest stable release
PHP 5.3 at minimum or latest stable release
PHP MySQL module must be installed and enabled
PHP CLI must be installed
PHP gettext extension must be installed and enabled for text translation
Please note that on most distro this extension is already compiled and shipped with PHP, so no need to worry
about this
PHP mbstring extension must be installed and enabled for unicode detection
Please note that on most distro this extension is already compiled and shipped with PHP, so no need to worry
about this
PHP GD extension must be installed and enabled to draw graphs
PHP IMAP extension must be installed and enabled to poll Emails from a mailbox
This extension will be used by playSMS for Email to SMS plugin
PHP Mcrypt must be installed to get composer to work properly
Access to SMTP server for sending Email
SMTP server software can be installed locally

4
Prerequisite

You can install, configured and start Postfix as your SMTP server
At least one console browser such as lynx, wget or curl should be installed
Downloaded playSMS package from SF.net or latest source code from Github

Minimum Brainware Requirements

Linux system administrator's or developer's required skills:

Understand howto make sure required softwares above are installed

Understand howto configure installed web server
The book will focus on server administrator, developer or installer who understand howto configure Apache2
Understand howto create/drop MySQL database
Understand howto insert SQL statements into created database
Basic knowledges to manage Linux
Must have the skill to navigate in console mode

5
Ubuntu Setup

Ubuntu Setup
Before installing playSMS the server must be prepared by installing required applications.

In this chapter the preparation is written for Ubuntu with Apache2, MySQL and PHP.

1. Upgrade Ubuntu

sudo apt -y update

sudo apt -y upgrade

2. Install LAMP stack and some PHP extensions

sudo apt install apache2 libapache2-mod-php5 mysql-server php5 php5-cli php5-mysql php5-mcrypt php5-gd php5-imap
php5-curl

3. Enable mcrypt extension manually

sudo php5enmod mcrypt

4. Restart apache2

sudo service apache2 restart

5. Browser http://localhost and see if the web server is serving

6. Back to Linux console and setup MySQL server. Setup MySQL root password

mysqladmin -uroot -p password <your_new_secure_password>

MySQL first time password is empty, just press Enter when prompted.

7. Create playSMS database

mysqladmin -uroot -p create playsms

8. Download playSMS package and save it in the server

We are ready to install playSMS. Next, you need to choose installation method. Choose one which is easier. For starter I
recommend to choose installation using provided install script.

6
Installation Using Install Script

Installation Using Install Script

Install playSMS using install script install-playsms.sh . The script is included in playSMS release package. Current official
release is playSMS version 1.4.2.

Please note that before following below steps you need to cover all steps required in Ubuntu Setup.

1. Extract playSMS package and go there (For example in /usr/local/src)

sudo tar -zxf playsms-1.4.2.tar.gz -C /usr/local/src

ls -l /usr/local/src/
cd /usr/local/src/playsms-1.4.2/

2. Copy install.conf.dist to install.conf and edit install.conf

Read install.conf and make changes to suit your system configuration

sudo cp install.conf.dist install.conf

sudo nano install.conf

3. Run installer script

sudo ./install-playsms.sh

4. Configure rc.local to get playsmsd started on boot

Look for rc.local on /etc , /etc/init.d or /etc/rc.d/init.d

When you found it edit that rc.local and put:

/usr/local/bin/playsmsd start

on the bottom of the file (before exit if theres an exit command).

This way playsmsd will start automatically on boot.

Note:

After successful installation, please run command ps ax and see if playsmsd is running

ps ax | grep playsms
4069 pts/12 S 0:00 /usr/bin/php -q /usr/local/bin/playsmsd /etc/playsmsd.conf schedule
4071 pts/12 S 0:00 /usr/bin/php -q /usr/local/bin/playsmsd /etc/playsmsd.conf dlrssmsd
4073 pts/12 S 0:00 /usr/bin/php -q /usr/local/bin/playsmsd /etc/playsmsd.conf recvsmsd
4075 pts/12 S 0:00 /usr/bin/php -q /usr/local/bin/playsmsd /etc/playsmsd.conf sendsmsd

Run several checks

sudo playsmsd status

sudo playsmsd check

Stop here and review your installation steps when playsmsd is not running

Consider to ask question in playSMS forum when you encountered a problem

If all seems to be correctly installed you may try to login from web browser

URL : http://[your web server IP]/playsms/

Default admin username : admin
Default admin password : admin

7
Installation Using Install Script

8
Installation Without Install Script

Installation Without Install Script

Install playSMS without using install script. Current official release is playSMS version 1.4.2.

Please note that before following below steps you need to cover all steps required in Ubuntu Setup.

1. Extract playSMS package and go there (For example in /usr/local/src)

sudo tar -zxf playsms-1.4.2.tar.gz -C /usr/local/src

ls -l /usr/local/src/
cd /usr/local/src/playsms-1.4.2/

2. Run getcomposer.sh

sudo ./getcomposer.sh

3. Create playSMS web root, log, lib and set ownership to user www-data or web server user

Assumed that your web root is /var/www/html and your web server user is www-data

sudo mkdir -p /var/www/html/playsms /var/log/playsms /var/lib/playsms

sudo chown -R www-data /var/www/html/playsms /var/log/playsms /var/lib/playsms

Please note that there are Linux distributions using apache as web server user instead of www-data

Also note that there are Linux distributions set /var/www as web root instead of /var/www/html

4. Copy files and directories inside web directory to playSMS web root and set ownership to web server user

sudo cp -R web/* /var/www/html/playsms

sudo chown -R www-data /var/www/html/playsms

5. Setup database (import database)

mysqladmin -u root -p create playsms

mysql -u root -p playsms < db/playsms.sql

6. Copy config-dist.php to config.php and then edit config.php

sudo cp /var/www/html/playsms/config-dist.php /var/www/html/playsms/config.php

sudo nano /var/www/html/playsms/config.php

Please read and fill all fields with correct values

7. Enter daemon/linux directory, copy files and folder inside

sudo cp daemon/linux/etc/playsmsd.conf /etc/playsmsd.conf

sudo cp daemon/linux/bin/playsmsd.php /usr/local/bin/playsmsd
sudo chmod +x /usr/local/bin/playsmsd

8. Just to make sure every paths are correct, please edit /etc/playsmsd.conf

nano /etc/playsmsd.conf

9
Installation Without Install Script

Make sure that PLAYSMS_PATH is pointing to a correct playSMS installation path (in this example to
/var/www/html/playsms )

Also Make sure that PLAYSMS_BIN is pointing to a correct playSMS daemon scripts path (in this example to
/usr/local/bin )

9. Start playsmsd now from Linux console, no need to reboot

sudo playsmsd start

10. Configure rc.local to get playsmsd started on boot

Look for rc.local on /etc , /etc/init.d or /etc/rc.d/init.d

When you found it edit that rc.local and put:

/usr/local/bin/playsmsd start

on the bottom of the file (before exit if theres an exit command).

This way playsmsd will start automatically on boot.

Note:

After successful installation, please run command ps ax and see if playsmsd is running

ps ax | grep playsms
4069 pts/12 S 0:00 /usr/bin/php -q /usr/local/bin/playsmsd /etc/playsmsd.conf schedule
4071 pts/12 S 0:00 /usr/bin/php -q /usr/local/bin/playsmsd /etc/playsmsd.conf dlrssmsd
4073 pts/12 S 0:00 /usr/bin/php -q /usr/local/bin/playsmsd /etc/playsmsd.conf recvsmsd
4075 pts/12 S 0:00 /usr/bin/php -q /usr/local/bin/playsmsd /etc/playsmsd.conf sendsmsd

Run several checks

sudo playsmsd status

sudo playsmsd check

Stop here and review your installation steps when playsmsd is not running

Consider to ask question in playSMS forum when you encountered a problem

If all seems to be correctly installed you may try to login from web browser

URL : http://[your web server IP]/playsms/

Default admin username : admin
Default admin password : admin

10
Upgrades

Upgrades
This sub-chapter contains information on how to upgrade playSMS.

11
Version 0.9.9.2 to 1.0

Upgrade from Version 0.9.9.2 to 1.0

We have 9 steps to follow to successfully upgrade an installed unmodified playSMS version 0.9.9.2 to 1.0.

Follow them correctly and in order.

1. Stop current playSMS daemon

sudo playsmsd stop

sudo playsmsd check

2. Backup everything related to installed playSMS 0.9.9.2

Backup playSMS database:

playSMS DB as SQL file, example DB name is playsms :

mysqldump -u root -p --add-drop-table playsms > playsms.sql

Note that option --add-drop-table above is important, do not miss it.

Backup playSMS files and folders:

playSMS daemon scripts at /usr/local/bin/

playSMS daemon config at /etc/playsmsd
playSMS files at web folder /var/www/html/playsms
WARNING:

Backup process is very important

Do not continue if you have any hesitation
Ask a lot if you have doubt
You must make sure that you know how to restore them
3. Remove all old playSMS files at web folder

sudo rm -rf /var/www/html/playsms/*

WARNING:

Prior to running above rm -rf /var/www/html/playsms/* command you must make sure that you have the backup
And also make sure that you type the command correctly in the correct location
4. Install playSMS version 1.0 in the same server with the same DB and the same web folder

5. Stop playSMS daemon

sudo playsmsd stop

sudo playsmsd check

6. Re-insert your backup playSMS DB sql file (DB sql file dump from previous installation) to the same DB

mysql -uroot -p playsms < playsms.sql

7. Upgrade DB

Get DB upgrade SQL from GitHub repository

wget -c https://raw.githubusercontent.com/antonraharja/playSMS/master/db/playsms-upgrade_0.9.9.2_to_1.0.sql

12
Version 0.9.9.2 to 1.0

re-insert that upgrade DB file into current playSMS DB

mysql -uroot -p playsms < ./playsms-upgrade_0.9.9.2_to_1.0.sql

8. Start playSMS daemon

sudo playsmsd start

sudo playsmsd check

9. Verify installation after upgrade

13
Version 1.0 to 1.1

Upgrade from Version 1.0 to 1.1

We have 7 steps below that must be followed sequentially to successfully upgrades an installed, unmodified, playSMS
version 1.0 to playSMS version 1.1.

Essentially upgrades means that:

1. You backup old files and database

2. Then you get the new version and replace all old files
3. Then you remove unused plugins
4. Then you upgrade the database with SQL upgrade file from new version

Skim this page from top to bottom before start. Follow them correctly and in order.

Let's start.

1. Stop current playSMS daemon

sudo playsmsd stop

sudo playsmsd check

2. Backup everything related to installed playSMS 1.0

Backup playSMS database:

playSMS DB as SQL file, example DB name is playsms :

mysqldump -u root -p --add-drop-table playsms > playsms.sql

Please note that the option --add-drop-table above is very important, do not miss it.

Backup playSMS files and folders:

playSMS daemon script at /usr/local/bin/playsmsd

playSMS daemon config at /etc/playsmsd
playSMS files at web folder /var/www/html/playsms
WARNING:

Backup process is very important

Do not continue if you have any hesitation
Ask a lot if you have doubt
You must make sure that you know how to restore them
3. Copy files from playSMS version 1.1 to replace old files

Download playsms-1.1.tar.gz from Sourceforge, visit playSMS Download for more information.

Run below commands to extract downloaded playSMS and replace old files:

sudo tar -zxf playsms-1.1.tar.gz -C /usr/local/src

ls -l /usr/local/src/
cd /usr/local/src/playsms-1.1/
sudo cp -rR web/* /var/www/html/playsms
sudo cp daemon/linux/bin/playsmsd /usr/local/bin

4. Remove unused plugins

14
Version 1.0 to 1.1

cd /var/www/html/playsms
sudo rm -rf plugin/gateway/gnokii
sudo rm -rf plugin/gateway/msgtoolbox

5. Upgrade DB

SQL upgrade file is available on playsms-1.1.tar.gz .

mysql -uroot -p playsms < /usr/local/src/playsms-1.1/db/playsms-upgrade_1.0_to_1.1.sql

6. Start playSMS daemon, and make sure its started (PIDS are displayed)

sudo playsmsd start

sudo playsmsd check

7. Verify installation after upgrade

15
Upgrade to Version 1.3.1

Upgrade to Version 1.3.1

We have a few steps below that must be followed sequentially to successfully upgrades an installed, unmodified, playSMS
version 1.1, 1.2, 1.2.1 or 1.3 to playSMS version 1.3.1.

Please note that upgrade instructions in this article are not compatible with playSMS 1.0 and before.

Essentially upgrades means that:

1. You backup old files and database

2. Then you get the new version and replace all old files
3. Then you upgrade the database with SQL upgrade file from new version

Skim this page from top to bottom before start. Follow them correctly and in order.

Let's start.

1. Stop current playSMS daemon

sudo playsmsd stop

sudo playsmsd check

2. Backup everything related to installed playSMS 1.1, 1.2, 1.2.1 or 1.3

Backup playSMS database:

playSMS DB as SQL file, example DB name is playsms :

mysqldump -u root -p --add-drop-table playsms > playsms.sql

Please note that the option --add-drop-table above is very important, do not miss it.

Backup playSMS files and folders:

playSMS daemon script is /usr/local/bin/playsmsd

playSMS daemon config is /etc/playsmsd.conf
playSMS files are located at web folder /var/www/html/playsms
WARNING:

Backup process is very important

Do not continue if you have any hesitation
Ask a lot if you have doubt
You must make sure that you know how to restore them
3. Copy files from playSMS version 1.3.1 to replace old files

Download playsms-1.3.1.tar.gz from Sourceforge, visit playSMS Download for more information.

Run below commands to extract downloaded playSMS and replace old files:

sudo tar -zxf playsms-1.3.1.tar.gz -C /usr/local/src

ls -l /usr/local/src/
cd /usr/local/src/playsms-1.3.1/
sudo cp -rR web/* /var/www/html/playsms
sudo cp daemon/linux/bin/playsmsd.php /usr/local/bin/playsmsd
sudo chmod 755 /usr/local/bin/playsmsd

4. Upgrade DB

SQL upgrade file is available on playsms-1.3.1.tar.gz .

16
Upgrade to Version 1.3.1

If you upgrade from playSMS 1.1 to 1.3.1:

mysql -uroot -p playsms < db/playsms-upgrade_1.1_to_1.3.1.sql

If you upgrade from playSMS 1.2 or 1.2.1 to 1.3.1:

mysql -uroot -p playsms < db/playsms-upgrade_1.2_or_1.2.1_to_1.3.1.sql

If you upgrade from playSMS 1.3 to 1.3.1:

mysql -uroot -p playsms < db/playsms-upgrade_1.3_to_1.3.1.sql

5. Start playSMS daemon, and make sure its started (PIDS are displayed)

playsmsd /etc/playsmsd.conf start

playsmsd /etc/playsmsd.conf check
playsmsd /etc/playsmsd.conf version

6. Verify installation after upgrade

17
Version 1.3.1 to 1.4

Upgrade from Version 1.3.1 to 1.4

We have 6 steps below that must be followed sequentially to successfully upgrades an installed, unmodified, playSMS
version 1.3.1 to playSMS version 1.4.

Essentially upgrades means that:

1. You backup old files and database

2. Then you get the new version and replace all old files
3. Then you remove unused plugins
4. Then you upgrade the database with SQL upgrade file from new version

Skim this page from top to bottom before start. Follow them correctly and in order.

Let's start.

1. Stop current playSMS daemon

sudo playsmsd stop

sudo playsmsd check

2. Backup everything related to installed playSMS 1.3.1

Backup playSMS database:

playSMS DB as SQL file, example DB name is playsms :

mysqldump -u root -p --add-drop-table playsms > playsms.sql

Please note that the option --add-drop-table above is very important, do not miss it.

Backup playSMS files and folders:

playSMS daemon script at /usr/local/bin/playsmsd

playSMS daemon config at /etc/playsmsd
playSMS files at web folder /var/www/html/playsms
WARNING:

Backup process is very important

Do not continue if you have any hesitation
Ask a lot if you have doubt
You must make sure that you know how to restore them
3. Copy files from playSMS version 1.4 to replace old files

Download playsms-1.4.tar.gz from Sourceforge, visit playSMS Download for more information.

Run below commands to extract downloaded playSMS and replace old files:

sudo tar -zxf playsms-1.4.tar.gz -C /usr/local/src

ls -l /usr/local/src/
cd /usr/local/src/playsms-1.4/
sudo cp -rR web/* /var/www/html/playsms
sudo cp daemon/linux/bin/playsmsd.php /usr/local/bin/playsmsd
chmod +x /usr/local/bin/playsmsd

4. Upgrade DB

SQL upgrade file is available on playsms-1.4.tar.gz .

18
Version 1.3.1 to 1.4

mysql -uroot -p playsms < /usr/local/src/playsms-1.4/db/playsms-upgrade_1.3.1_to_1.4.sql

5. Start playSMS daemon, and make sure its started (PIDS are displayed)

sudo playsmsd start

sudo playsmsd check

6. Verify installation after upgrade

19
Version 1.4 to 1.4.2

Upgrade from Version 1.4 to 1.4.2

We have 6 steps below that must be followed sequentially to successfully upgrades an installed, unmodified, playSMS
version 1.4 to playSMS version 1.4.2.

Essentially upgrades means that:

1. You backup old files and database

2. Then you get the new version and replace all old files
3. Then you remove unused plugins
4. Then you upgrade the database with SQL upgrade file from new version

Skim this page from top to bottom before start. Follow them correctly and in order.

Let's start.

1. Stop current playSMS daemon

sudo playsmsd stop

sudo playsmsd check

2. Backup everything related to installed playSMS 1.4

Backup playSMS database:

playSMS DB as SQL file, example DB name is playsms :

mysqldump -u root -p --add-drop-table playsms > playsms.sql

Please note that the option --add-drop-table above is very important, do not miss it.

Backup playSMS files and folders:

playSMS daemon script at /usr/local/bin/playsmsd

playSMS daemon config at /etc/playsmsd
playSMS files at web folder /var/www/html/playsms
WARNING:

Backup process is very important

Do not continue if you have any hesitation
Ask a lot if you have doubt
You must make sure that you know how to restore them
3. Copy files from playSMS version 1.4.2 to replace old files

Download playsms-1.4.2.tar.gz from Sourceforge, visit playSMS Download for more information.

Run below commands to extract downloaded playSMS and replace old files:

sudo tar -zxf playsms-1.4.2.tar.gz -C /usr/local/src

ls -l /usr/local/src/
cd /usr/local/src/playsms-1.4.2/
sudo cp -rR web/* /var/www/html/playsms
sudo cp daemon/linux/bin/playsmsd.php /usr/local/bin/playsmsd
chmod +x /usr/local/bin/playsmsd

4. Upgrade DB

SQL upgrade file is available on playsms-1.4.2.tar.gz .

20
Version 1.4 to 1.4.2

mysql -uroot -p playsms < /usr/local/src/playsms-1.4.2/db/playsms-upgrade_1.4_to_1.4.2.sql

5. Start playSMS daemon, and make sure its started (PIDS are displayed)

sudo playsmsd start

sudo playsmsd check

6. Verify installation after upgrade

21
Gateway Installation

Gateway Installation
Gateway installation.

22
Kannel

Kannel
Kannel.

23
Kannel

Kannel Installation on Ubuntu

Prerequisite:

You need Internet access

You need to have sudo access
Your Ubuntu or Debian must be configured correctly so that the apt will not fail

Below are steps required to install Kannel in Ubuntu or Debian:

1. Install Kannel

sudo apt install kannel

sudo mkdir -p /var/log/kannel /var/run/kannel /var/spool/kannel/store
sudo chown -R kannel /var/log/kannel /var/run/kannel /var/spool/kannel/store
sudo usermod -a -G dialout kannel

2. Edit /etc/default/kannel to activate smsbox

sudo sed -i 's/#START_SMSBOX/START_SMSBOX/' /etc/default/kannel

3. Backup original kannel.conf

sudo cp /etc/kannel/kannel.conf /etc/kannel/kannel.conf.dist

4. Download example kannel.conf and replace existing /etc/kannel/kannel.conf

wget -c https://raw.githubusercontent.com/antonraharja/playSMS/master/contrib/kannel/kannel.conf
sudo cp kannel.conf /etc/kannel/
ls -l /etc/kannel/

5. Edit /etc/kannel/kannel.conf . Replace http://CHANGE_THIS_TO_YOUR_PLAYSMS_URL with your playSMS URL, for example
with http://localhost/playsms

6. Read the rest of kannel.conf and setup your Kannel.

In the example kannel.conf you will see several option values with all uppercase, such as
KANNELADMIN_CHANGE_THIS, you have to change them. Of course you need to understand how to configure
kannel.conf properly, how to add modems and SMSCs when needed.

Below URL is the user guide for understanding kannel.conf : http://www.kannel.org/download/1.4.4/userguide-

1.4.4/userguide.html

7. Only after you have configured kannel.conf to suit your needs and your setups then you may restart Kannel

sudo /etc/init.d/kannel restart

8. Verify Kannel installation

ps ax | grep box
netstat -lnpt
tail -f /var/log/kannel/kannel.log

24
Kannel

25