General
Introduction
Documentation
Platforms
Supported Hardware
Package Content
Installation
Download
Server Install
Client Install
Gateway Install
Upgrade
Tech Info
Changelog
FAQ
Drivers
PDU format
Bugs / Todo
Related Links

Jump to Vim Home Page

SMSLink Server Installation Procedure

Please note: The installation instructions below will actually build and install both the server and the gateway module. For configuration instructions specific to the gateway module, please check this page.

Table of Contents

  1. Connect the hardware.
  2. FreeBSD: Configure serial port.
  3. Configure the modem (if needed).
  4. Install libmodem.
  5. Tailor libmodem configuration file.
  6. Untar the SMSLink package.
  7. Setup link with backend MySQL database (optional).
    1. Install MySQL server.
    2. Install MySQL client + headers.
    3. Configure the server module's access to the database.
  8. Build SMSLink server modules.
    1. Customize Makefile.
    2. Customize main header file (optional).
    3. The build process proper.
  9. Install server modules.
  10. Include SMS in the known services.
  11. Copy the "driver database" to /etc.
  12. Tailor the config file to your needs.
  13. Implement access control (optional).
  14. Create the inbox directory.
  15. Create the outbox directory (optional).
  16. Arrange for the service to be started at boot time.
  17. Test your installation.

Connect the hardware.

Assemble and connect the GSM module (power, serial and aerial). Test connectivity with Minicom (or any other serial communication program you feel comfortable with): the parameters are likely to be 9600, N, 8, 1. Type AT<cr>, you should get "OK" in return.

Please note: In order for this to work (as well as the rest of this install procedure), your kernel should be compiled with serial support (CONFIG_SERIAL -- most pre-compiled kernels are). If serial support was compiled as a module, that module should be loaded.

Then test the SIM card recognition and GSM network connectivity:

	AT+CPIN?
	SIM PIN

	AT+CPIN=1234
	OK

	AT+CPIN?
	READY

	AT+CREG?
	CREG: 0,1

This short dialog provided the SIM card with the PIN code it requested, then verified that the module did attach to the GSM network. For further details on those commands (and the SMS-related AT+ command set in general), see your module handbook or the "GSM Modules Tech Info" section on the Related Links page.


FreeBSD: Configure serial port.

(Please note: Failure to follow this step may lead to the "lopen_mdm_line() failed" error -- please read this, more specifically the note to FreeBSD users, for more details about it.)

Edit /etc/rc.serial, and add the following line (or a similar one depending on your needs, of course):

	modem d a 0

This calls the modem() function (also in rc.serial) with the dialin and dialout devices (ttyd and cuaa) and the specific device (ttyd0 and cuaa0). The modem function sets the necessary parameters, like crtscts, baud rates, etc. for the device.

Reboot the machine to activate the changes.

More details on this step at: http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/serial.html

Thanks a lot to Nicki de Wet for those valuable insights.


Configure the modem (if needed).

At this stage, you can disable the Network Registration unsollicited result code, as the server program will never use it anyway, and it might confuse it if present.

At the "AT" prompt interface, issue the following commands:

AT+CREG=0
AT&W

The first line will disable the aforementionned feature, the second will save that setting to the modem EEPROM, making it permanent.

Here, you can also take the opportunity to configure your modem for the highest supported speed on the serial line. A higher speed here will maximize throughput later. Recommended: 19200 bps, if supported by the device.

AT+IPR=?
AT+IPR=19200
AT&W

The first command queries the device for the speeds it supports. The second sets it to 19200 bps, and the last one commits the changes to the modem EEPROM. Please be aware that you will have to reconfigure your communication software before being able to save your changes, since the AT+IPR command takes effect immediately.


Install libmodem.

Either grab libmodem-1.5 or higher (you can get it here or there)
- or -
grab version 1.0.0 of the package from its official location or from here and apply the provided patch. Untar the source package and then patch it with Angelo's SMS patch and mine (combined in the file libmodem-1.0.0.pha.patch located here in the varia/patch/ directory).

Then, whatever the version, proceed to install it as mentionned in this package documentation.


Tailor libmodem configuration file.

Normally called /etc/modems by default, you should create a line there for each serial line(s) you'll connect the GSM module(s) to. I suggest creating a symlink from the original /dev/cua? device (/dev/ttyS? recommended if you're on Linux kernel 2.2.x or higher) to /dev/gsm (or /dev/gsm? if you plan to connect more then one).

The location of the file is controlled by the MDMFILE define, located in dial/modems.h.in, and a template modems file can be found in the etc directory (relative to the base of the libmodem package tree). As an example, here are lines that work for me:

gsm0:AT::+++:30:9600:CONNECT:D:::Z:H0:0
gsm1:AT::+++:30:9600:CONNECT:D:::Z:H0:0


Untar the SMSLink package.

First, grab the latest distribution tar file from the download page on this site.

Then, uncompress and untar this distribution package on your system, for instance under /usr/src.

Example:

	$ mv smslink-0.55b.tar.gz /usr/src
	$ cd /usr/src
	$ gunzip smslink-0.55b.tar.gz
	$ tar -xvf smslink-0.55b.tar

Setup link with backend MySQL database (optional).

As of version 0.55b, the SMSLink server module supports the use of a backend MySQL database to store incoming and outgoing (when queued) messages. This feature is optional, though -- both incoming and queued outgoing messages can also be stored in / as text files.

Should you wish to enable this feature, please follow these steps to install and configure all the required components.

Install MySQL server.

Please note that the back-end MySQL server doesn't have to reside on the same physical host as the SMSLink server module. sms_serv(1) is able to access its configured database back-end over the network.

So, on the host of your choosing, please install the MySQL server component (the details of that installation are beyond the scope of this document, please refer to the excellent MySQL documentation, or simply select the mysql package provided by your distribution). Arrange for the MySQL server component to be started at this host boot time.

When this is done, please use the provided ./varia/database/database.sql SQL script as input for the mysql client. This will create the MySQL objects required by SMSLink: the smsstore database and the dbschema, inbox and outbox tables.

Example:

	$ cd ./varia/database
	$ mysql -u root -p mysql < database.sql

Install MySQL client + headers.

On the host where the SMSLink server module will reside (the host with access to the GSM serial device(s)), you should install (at least) the MySQL client library and header files. Those will be required in order to compile the sms_serv(1) server module.

If you're using SuSE Linux distribution, the MySQL client library and header files are provided in the following packages:

  • mysql-shared-3.23.52-44 (client lib.)
  • mysql-devel-3.23.52-44 (header files)

The exact version of the package may vary, of course, but use of MySQL version 3.23 or higher is required for API reasons.

Configure the server module's access to the database.

Now, you should arrange for the sms_serv(1) module to be granted access to the smsstore database.

Using the mysql client, connect to the mysql database as the admistrator (typically root), and create a new user dedicated to SMSLink usage. We'll assume that you called this user smslink in the rest of this document (but you're free to call it any way you like).

The newly created smslink user should be granted at least the following rights on the smsstore database:

  • SELECT
  • INSERT
  • UPDATE
  • DELETE

Example:

mysql> GRANT ALL PRIVILEGES ON smsstore.* TO smslink@localhost IDENTIFIED BY 'smspass';

Then, copy to /etc the default gsmdbtab file provided in ./server and customize it to match your setup: it should contain a single line observing the following format:

dbserver:dbname:user:password

Example:

	localhost:smsstore:smslink:smspass

For obvious security reasons, make sure this file is owned by the user that you plan to run the sms_serv module as, and chmod it 400.


Build SMSLink server modules.

In order to start the server modules build process, change directory to ./smslink-<version>/server. The first step will be to make sure the Makefile there matches your environment. In a second, optional step, advanced users may also fine-tune the main header file.

Customize Makefile.

Edit the first part of ./smslink-<version>/server/Makefile to accomodate your platform and feature choices.

  • First make sure to uncomment the line corresponding to your platform (and make sure only one such line is uncommented). More on supported platforms here.
  • If you'd like to use the MySQL backend database feature, make sure to uncomment the line that reads SQL = -DWITH_MYSQL (beware: this requires the presence of MySQL client lib. and header files on this host (see above for details)).
  • For building the server with debugging enabled, you can uncomment the line that reads DEBUG = -DINCL_DEBUG_CODE. Please note: as of 0.54b, the use of this flag is mostly obsolete. Debugging is now turned on by the -d command-line option. If, on the other hand, you need a build that includes debugging symbols, you can get it by invoquing make as: CFLAGS=-g make.
  • If your environment requires it (e.g. your MySQL client library and / or header files are located in an unusual place), please use the IEXTRA and LEXTRA lines (commented out by default) to add custom entries to your compiler libraries and / or include files search paths.
  • On the lines that follow, you can also customize the names of the compilation chain tools. Please use with care !
  • And last, you get an opportunity to customize the installation paths (/usr/local/bin and /usr/local/man by default).

Customize main header file (optional).

Please note: The main header file, as shipped, should fit most setups and I don't recommed first-time users try to alter it in any significant way. However, when more familiar with the inner working of the program, those options may be of valuable help.

For more fine-tuning of the server modules operation, you can customize some entries in the main header file (server/sms_serv.h). A few usefull ones will be described below. Please note that the most often used ones have been added as command-line options as of version 0.55b (and it is our plan to soon have all of them available through some global configuration file).

Should you wish to make use of the "prog" feature for some or all the devices, you should edit server/sms_serv.h at this point and customize the line that reads:

	#define SMS_PROG_NAME           "sms-recv.pl"

to match the program name you would like the incoming messages to be fed to. Make sure to use the full path name when the required program doesn't live in a directory covered by the PATH environment variable (please remember that init(8), if this will be the one to start sms_serv(1), uses a minimal PATH).

The build process proper.

You can then type make to initiate the build process. Depending on the platform, a few warnings might be issued during the compilation phase, but those can be safely ignored.


Install SMSLink server modules.

When compiled successfully, type make install as root.

Note that this will install both sms_serv(1) and sms2mailgw(1) (as well as all related man pages). You can choose to compile only the server module by typing make sms_serv, but there is no separate install target (yet).


Include SMS in the known services.

Edit your /etc/services file, and add the following line:

sms             6701/tcp                        # SMS Link Server


Copy the "driver database" to /etc.

In order for the server program to be able to work with different brands of GSM modules, some primitive form of driver is now provided. The default file is found in the server/ directory, and is called gsmcaps. If this is a first install, or you didn't tinker with the previous version of this file, just copy this file to /etc. If you're using a modified version of the file, please review the diffs and integrate them manually.

This file will NOT be installed automatically by the make install procedure, in order to avoid overwriting any customization of yours.

Should you indeed have had to customize this file, please keep me posted so that I can distribute your changes with the next release.


Tailor the config file to your needs.

The config file, by default, is called /etc/gsmdevices. It contains, among others, the PIN code, PUK code, and caller ID of the installed SIM card. You'll obviously need to change those to match your own SIM. A template file is located in the ./server directory, but it will NOT be copied in place by the installation process (to avoid overwriting the existing config when upgrading).

You should also consider which feature you want to enable for the device. Those features are controlled by the flags that make up the last field of each device record (as of version 0.54b). By default (if left empty), the only feature enabled are "poll" (poll the device at interval to check for incoming messages) and "inbox" (store those messages in an inbox file). Other selectable features are "dd" (attach a dedicated daemon the the device), "init" (initializes the device once, thereby saving time on future send), "prog" (feed the incoming messages to a program), "fast" (use "fast modem response") and "r4" (causes all messages to be read from the device, not just unread ones). Please refer to gsmdevices(5) for more details on those flags and their effects.

It is also likely that you'll want to customize the value of the "PINpause" parameter. But before doing it, I suggest you read the special coverage I gave this feature in question 2.1.10 of the accompanying FAQ.

WARNING: The format of this file changed between version 0.44b and version 0.46b of the server module, and again between version 0.46b and version 0.48b. Version 0.54b added an optional last field to the record. Then version 0.55b changed the format again by adding the "PINpause" parameter. Please refer to gsmdevices(5) or the header of the example gsmdevices file provided in the server/ source directory for more details on the file format.


Implement access control (optional).

Create a file called (by default) /etc/gsmaccess. It will contain a list of the IP addresses of the networks or machines that are allowed to connect to the server. In this file, lines beginning with a '#' are treated as comments. Blank lines are ignored. In case the file is not present, no access control will be implemented. The install process DOES NOT copy the template to /etc by default meaning no access control is put in place unless you copy it yourself.

Access control, when enabled, defaults to deny. Anything not specifically allowed is denied. So make sure that the /etc/gsmaccess file is not left empty and that each entry follows the stated format (invalid entries are ignored). See gsmaccess(5) for format details and examples.


Create the inbox directory.

Create a directory called smslink under /var/spool (see the define called MBOX_FILE in sms_serv.h) and make sure the rights and ownership are consistent with the user the server will run as and the other external applications that will have to access it (root:root, 0750, for instance).

The server component will create a file called inbox there.


Create the outbox directory (optional).

Note: This step is required only for versions 0.55b or greater of the server, and then only when you want to make use of the queueing feature in "file" mode.

You should now have a directory called smslink under /var/spool already (see the previous installation step).

In this directory, create a sub-directory called outbox (same rights and ownership as its parent). The server component will use it to store queued items when / if you use the "file" queueing method.

Once this is done, in order to enable the queueing feature in the server, you need to either edit ./server/sms_serv.h and set OBCHKINTERVAL to a non-zero value (the elapsed time in seconds between two outbox queue runs), or start the server with the -o / --obchkinterval command-line option followed by the interval in seconds.


Arrange for the service to be started at boot time.

Edit your init scripts to have the service(s) started at boot time. Normally, it requires root capabilities to successfully start the service, as only root can access the GSM device by default. This is not a problem since it will most likely be started by init. You might consider it even safer to create a special group, grant this group rw access to the serial device the GSM module is attached to, and then setgid the binary to this group.

A sample System V init script and its accompanying configuration file are now provided in the archive, below ./varia/scripts/SuSE/. They were designed with SuSE Linux 9.3 Pro in mind, but can certainly be used (at least as a starting point) for other distributions as well.

In the case of SuSE, simply copy ./varia/scripts/SuSE/init.d/smslink to /etc/init.d and ./varia/scripts/SuSE/sysconfig/smslink to /etc/sysconfig. You may wish to edit the default values provided in /etc/sysconfig/smslink to better suit your needs. The init script will take care of starting both daemons (sms_serv(1) and sms2mailgw(1)). Test that its working properly by invoquing the script manually (you can have a look at your syslog file to check that both modules start successfully):

# /etc/init.d/smslink start
[...]
# /etc/init.d/smslink stop

Once you're satisfied that the script is working properly, you can use the following command to make sure that the startup and shutdown will happen automatically:

# cd /etc/init.d
# insserv smslink
# ln -s /etc/init.d/smslink /usr/sbin/rcsmslink

If you're using another distro, please adapt those directions accordingly. Contributed startup scripts are provided for RHEL / Fedora in ./varia/scripts/RHEL/.

Please note: if you install under SuSE / OpenSuSE and decide NOT to use the MySQL backend feature (or the MySQL database will be hosted on a separate machine), please remove "mysql" from the listed dependencies of the SMSLink startup script, i.e. edit the line that reads:

# Required-Start: syslog mysql

Test your installation.

Now that the server is installed, configured and started, try to connect to it. The easiest way is to telnet to it (with a telnet client supporting "line mode" -- Linux is perfect, of course). Type:

	$ telnet my-server 6701

You should be greeted with the SMS> prompt. Reproduce a session similar to the following:

	SMS> set dest = 12345 (your mobile phone number)
	Ok
	SMS> set user = "yourself"
	Ok
	SMS> set msg = "Hello GSM World!"
	Ok
	SMS> send

Now sit back and watch...

That's all, Folks...


Last Modified: May 20th, 2007.
philipa STRUDEL scarlet PUNKT be
SourceForge Logo