Project SMSLink - FAQ

Table of Contents

• Q1.1 Will SMSLink support Nokia phones + DataSuite cable ?
  
• Q1.2 Can I use SMSLink to send logos / pictures / ringtones to GSMs ?
  

Server issues

• Q2.1.1 The server doesn't seem to process incoming messages
  
• Q2.1.2 Run-time error after upgrading to 2.2.x kernel
  
• Q2.1.3 Server hanging in the beginning of the sending process
  
• Q2.1.4 The "blopen_mdm_line() failed" error message
  
• Q2.1.4' The "lopen_mdm_line() failed" error message
  
• Q2.1.5 The server is running, but I can't connect.
  
• Q2.1.6 Enabling debugging in the program modules.
  
• Q2.1.7 Using script(1) to generate a debug trace for the server.
  
• Q2.1.8 Can't get "fast" mode working.
  
• Q2.1.9 The "unsupported numplan (...)" message.
  
• Q2.1.10 The "+CMS ERROR: 515" message.
  
• Q2.1.11 The "sms_serv: lopen_mdm_line() failed: Unknown error" message.
  

• Q2.2.1 The "MBC poll missed {...}" message.
  
• Q2.2.2 Should I disable the mailbox check ?
  

• Q2.3.1 sendsms gives very poor performances.
  
• Q2.3.2 sendsms always fails against a server in "dd" mode.
  
• Q2.3.3 Using script(1) to generate a debug trace for the client.
  

• Q2.4.1 Can I use SMSLink to send Nagios alert messages ?
  

• Q3.1 Using a multi-serial board / more than 2 serial ports
  
• Q3.2 Hardware or software flow control.
  
• Q3.3 Handling devices that don't support flow control
  
• Q3.4 The "+CMS ERROR: 514" message
  
• Q3.5 Manually sending an SMS to debug the modem replies
  

General questions

Q1.1 Will SMSLink support Nokia phones + DataSuite cable ?

Maybe later.

Folding the Gnokii-developped Nokia protocol into SMSLink source tree is not on my TODO list right now.

Q1.2 Can I use SMSLink to send logos / pictures / ringtones to GSMs ?

Since a lot of users requested this feature already, and since I came across technical information on how to handle that kind of messages, I might indeed try to add that feature in the not too distant future (if only because it looks like fun hacking it).

The way I see it, if somebody else was able, in the mean time, to come out with a program that could generate the raw PDU string containing those pictures / logos / ringtones, I could easily (I hope) integrate a function in SMSLink allowing the user to load a pre-formatted PDU string from file and then send it unmodified to the destination GSM.

Software-related questions

Server issues

Q2.1.1 The server doesn't seem to process incoming messages

This polling of the devices occurs only at specified interval (by default, once an hour). This interval can of course be customized to the administrator's desire. To do so, in the project source tree, edit the file server/sms_serv.h and change the line reading

#define MBCHKINTERVAL 3600 /* mailbox check interv.(sec)*/

to define the appropriate number of seconds. It is not recommended to set it lower than 120 (once every 2 min.). Please remember than the more often you poll your devices for incoming messages, the more you reduce the window for sending outgoing messages. As an administrator, you have to find the right balance between both tasks according to the application needs.

To disable this polling altogether, set MBCHKINTERVAL to 0 (zero).

The server module will report the value of this parameter through syslog when loading, with messages like the following:

Nov 6 15:09:55 vger sms_serv[1192]: mailbox check function enabled, first check in 3600 secs.

At the present, this parameter can only be choosen at compile-time, but future versions of the server should allow the administrator to specify this interval on the command-line.

Q2.1.2 Run-time error after upgrading to 2.2.x kernel

----------cut-----------
got </dev/gsm>, now sending...
tty_io.c: process 160 (sms_serv) used obsolete /dev/cua0 - update software
to use /dev/ttyS0
----------cut-----------

To solve this error, go to /dev, remove your gsm softlink to cuax and create a new one (with the same name) to ttySx (where x is also the same, obviously). As long as you kept the same name for the gsm softlink, there's nothing to change in the configuration files.

Q2.1.3 Server hanging in the beginning of the sending process

----------cut-----------
got </dev/gsm>, now sending...
----------cut-----------

...and then hangs.

What is most likely happening is that the directory where the "libmodem" library would like to store its lock file doesn't exist. By default, libmodem expects a directory called /usr/spool/uucp. It should be owned uucp:uucp (or root:root if the uucp user doesn't exist on your system), and mode drwxrwxrwt (watch for the 't' bit). It is indeed not created by default on all distributions and / or configurations. Just create it with the aforementionned rights and ownership if not present. You can also edit dial/modems.h.in in the libmodem source tree and alter the LOCKDIR define (not the recommended solution).

Please also read the following question.

Q2.1.4 The "blopen_mdm_line() failed" error message

The symptoms for this problem here are similar to the previous case. When you type "send", the server answers:

----------cut-----------
got </dev/gsm>, now sending...
----------cut-----------

...and then hangs.

In the syslog log file, you'll find an entry saying something like:

----------cut-----------
...sms_serv[1147]: call to blopen_mdm_line() failed.
----------cut-----------

Flow control problem:
What could be happening is that the flow control to the GSM module is no set correctly. Please check the last field of the relevant line in /etc/modems. A value of 0 (zero) means hardware flow control. This seems to work fine with Falcom A1 and Wavecom WMO1. If you have problems with a Falcom A2, you might want to try with a value of 1 (one). This will use software flow control (XON-XOFF).

Thanks to Piero Baudino for pointing that out.

Error in SMSLink configuration file:
Should you notice the dreaded

----------cut-----------
...sms_serv[1147]: call to blopen_mdm_line() failed.
----------cut-----------

appear in your logs, and after ruling out the other possible causes (see above 2 entries), you might want to check your /etc/gsmdevices for duplicate entries. That error can occur when you mistakenly defined multiple entries in /etc/gsmdevices for the same device (identical first field in /etc/gsmdevices). The sms_serv(1) daemon will then consider it has 2 modules attached and try to use the one it has twice at the same time (when multiple clients are sending simultaneously), resulting (for the second client) in a failure to lock it.

Thanks to Stanley Hopcroft for reporting this.

Insufficient privileges:
Trying to run sms_serv(1) as a user that doesn't have enough privileges to write to the serial port device the GSM module is attached to will cause the same error.

Value too small for the libmodem timeout:
The value of the internal libmodem timeout that triggers the EMDMNOFDSET error when tripped is controlled by the "dl" field in your /etc/modems file. By default, it is set to 30 secs. Setting too small a value for that parameter could also cause the error. I'm mentionning this for the sake of completion, as none ever reported seeing the error because of this -- possibly because none ever attempted to mess with this value.

Defective cable or faulty GSM module:
Any hardware problem preventing proper communication between the server daemon and the GSM module will cause the error in question.

No GSM module attached or module turned off:
Trying to run sms_serv(1) on a host where no GSM module is attached, or where the GSM module is powered off will, once again, cause the same error.

libmodem config and GSM module don't agree on line speed:
Here, I'm quoting an email from Jason Whiting. Thanks a lot to him for reporting his findings.

  Combing through the strace dump with a colleague of mine, he noticed that 
  the modem wasn't returning valid data. (This is also indicated in 
  /var/adm/libmodem.log by the line 'read >>  << from modem'.) Turns out 
  this was a mismatch in the baud rates set in the modem and in /etc/modems.

  Using minicom, I was talking to the modem at 115200, but my /etc/modems was 
  set for 9600... Feeling unbelievably stupid, I reset minicom to 9600, but 
  could then not talk to the modem either. (Setting /etc/modems to 115200 
  returned an 'Invalid baud rate' error.) So back to 115200 in minicom, do 
  'AT+IPR=9600' and 'AT&W', exit, restart minicom at 9600 - and voila!

  With the modem now set to 9600 and /etc/modems also at 9600, I restarted 
  sms_serv as root, and sent a test message using sendsms. Received it in 
  good order too. :)

  I realise this is an elemental mistake - and one I should have caught on 
  to! - but was wondering if it would perhaps not be worth including this in
  the FAQ as another possible cause for 'call to blopen_mdm_line() failed'?

  (I do not know if the modem not auto-scaling to the /etc/modems speed is 
  applicable only to the Falcom A2D...)

  In summary:

  * I was able to communicate with the Falcom A2D in minicom at 115200.
  * My /etc/modems entry was set for 9600 (and didn't accept 115200 as valid).
  * The error I got was 'sms_serv: blopen_mdm_line() failed: FD was not set 
    when select returned (timeout)', and in libmodem.log there was an entry 
    'read >>  << from modem'.
  * In minicom, force the modem to 9600 with 'AT+IPR=9600', and write to 
    memory 'AT&W'.
  * Restart sms_serv (if /etc/modems changed), and now it should work.

Special note for FreeBSD users:
(thanks a ton to Nicki de Wet for finding that out).

It seems FreeBSD hosts should invoque a special serial port setup script at startup, which doesn't happen by default. To quote Nicki's email:

There is a page on serial comms at http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/serial.html which explains the details.

I modified /etc/rc.serial, and added the following line:

	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.

After doing this and restarting, I changed line_manage.c line 710 back to the original alarm(2) instead of alarm(5), and it now works as it should.

Q2.1.4' The "lopen_mdm_line() failed" error message

There is no difference (in the context of this error message) between this message and the previous one. Please refer to the FAQ entry above.

As a matter of fact, SMSLink code used to call the blopen_mdm_line() version of the function, but as of 0.54b-8, when working on performance improvement tweaks, I switched to using only the lopen_mdm_line() version. Please see the related changelog entry for details.

Q2.1.5 The server is running, but I can't connect.

bernward:~$ telnet vger sms
Trying 192.168.100.254...
Connected to vger.ste.scitex.com.
Escape character is '^]'.
Connection closed by foreign host.
bernward:~$

This is most likely due to an error in implementing the access control mechanism. Either you forgot to allow connection from that specific host / network, or the line which should allow access was dropped by the server due to some format error.

Also take into account that each entry in /etc/gsmaccess should contain a subnet mask. Make sure the host from which you're trying to open the connection is indeed part of the subnet you defined in the access file (to allow a single machine, use a subnet string of "/32").

Please also remember that the entries in the access file are scanned top-down and matched on a "first-fit" basis. This means that the order of the lines in the file is relevant, and that denying access to network X and then allowing access to host Y, member of network X, won't work. Put it the other way around.

A way of debugging this is first to look at the messages logged in the system log of the server. The number of valid ACL entries is mentionned, or the fact that access control is disabled in case no access file was found. Example:

Nov 15 16:17:04 vger sms_serv[1289]: successfully loaded 12 ACL entries.

Also, in case a connection is rejected based on the current set of ACL's, a message similar to the following is logged:

Nov 15 16:20:21 vger sms_serv[1289]: illegal connect from [192.168.100.10]

A good way to check the exact set of ACL's currently used by the server is to connect to it from an allowed machine (obviously), and to issue the "acl" command at the "SMS>" prompt.

Q2.1.6 Enabling debugging in the program modules.

Further on, I will explain how to use the script(1) utility to capture that debugging information and log it to file.

For SMSLink version as of 0.54b

The two main programs of the distribution, sms_serv(1) and sms2mailgw(1) now support the GNU getopt() function for handling command-line parameters, which mean you can use either long or short version of the options. One such option is "-d" or "--debug". Its use will enable debugging information at program startup. When used with no parameter, this option will enable all debugging info. A more restrictive set of information can be selected by playing with the flags used to build this parameter. See the man pages and the file called server/sms_serv.h for more information on the meaning of each flag. Full implementation of this system is still work in progress.

Also worthy to be mentionned is the fact that the current debugging level can be altered from the "interactive interface" of sms_serv, but this will of course only affect the current session (and neither its parent process, not other child processes). To do this, when connected, use the command "set debug = x" where x is the desired debug level in its decimal form. 0 (zero) disables it. "show debug", as expected, shows the current debug level.

In addition to the method described above, you can also use the older method described here below. That way, you're sure not to miss anything -- even though I will restrict the use of the older method to debugging information that really shouldn't be of interest outside of the developpment process.

For SMSLink version up until 0.52b-3

When faced with a tricky issue to debug (or when attempting to add support for a new brand of GSM module), you might need to turn debugging on in any of the program modules. I might also ask you to do this if you mail me for help: that way, you can simply forward me the collected debugging info.

Here are the steps involved in enabling the debugging (and capturing its output in a file). In the example below, I'll focus on the server module (sms_serv(1)), but the procedure is exactly the same for any other module.

Basically, you'll need to recompile the module with debugging enabled. So go to the source tree, and begin by issuing a make clean command.

Then edit the Makefile and uncomment the line which reads:

#DEBUG = -DINCL_DEBUG_CODE

(just remove the "#" sign in front). You can now recompile the module (make sms_serv). When finished, just copy the new executable in place or consider to launch it from the source tree (a version with debugging enabled is not meant for production use anyway).

Capturing the debug output and logging it to file

This applies to both debugging methods. For a detailed procedure, please see question 2.1.7 below.

Q2.1.7 Using script(1) to generate a debug trace for the server.

Debugging server sending through interactive session(s)

Use 2 different consoles, one for running the server and one for interacting with it. Both consoles need not be started on the same host, even.

You now want to start the server, but also make sure that any debug info it will output will be kept in a file for further analysis. The way to go is to use the script(1) utility (should be installed by default on most distros).

1./ server
- start a script

# script /tmp/sms-server.debug
Script started, file is /tmp/sms-server.debug

- "inside" the script, start the server in full debug mode

# ./sms_serv
- or -
# ./sms_serv --debug
(lots of debugging info output on the screen and dumped in the file -- the server is running now).

(now just leave it alone, switch to another console)

2./ interactive session(s) with the server
- Please note: steps 2 through 4 can be played several times simultaneously (from seperate consoles) to test the server's ability to process parallel requests.

- open an interactive session with the server

$ telnet server-name sms
(where server-name is the hostname or IP address of the server running SMSLink and sms is the service name. If not defined in /etc/services, use the port number instead [6701 by default]).

- you should get the SMS> prompt

3./ send an SMS
- at the SMS> prompt, fill-in the required fields:

SMS> set user = "you"
SMS> set dest = 1279182192
SMS> set msg = "Test message"
SMS> send
(of course, you should replace the destination GSM number in the example, or the actual set of commands you want to issue with some scenario that suits your purpose).

4./ watch the sending dialogue scroll by
- wait for the error to occur

- when the dialogue is over, leave the interactive interface

SMS> bye

(when this is done, switch back to the server console)

5./ server again
- the server process can now be stopped

# killall sms_serv

- exit the script session you started above (this will commit any unsaved debug info to the file).

# exit
Script done, file is /tmp/sms-server.debug

That's it. You can now browse through the debug trace, and correlate it with regular messages dumped to your syslog files (/var/log/messages and/or /var/log/syslog -- see /etc/syslog.conf to check which).

You can now mail me the .debug file. You could also do an extract of your system log file (/var/log/messages) for the entire test sessions (use timestamps to determine what is relevant). Of course, you can first edit those files to remove any phone / PIN number if you wish. Please remember that the communication is also logged in hex at some point - so please ensure consistency at that level if you decide to edit them.

Debugging incoming messages processing on the server

Use 2 different consoles, one for the server and one for watching it.

1./ server
- start a script

# script /tmp/sms-server.debug
Script started, file is /tmp/sms-server.debug

- start the server in full debug mode

# sms_serv -d

(now just leave it alone, switch to another console)

2./ server watching
- watch the system log file "live"

# tail -f /var/log/messages

(note: on some systems, that file is /var/adm/messages -- see /etc/syslog.conf to make sure).

3./ send an SMS from the required source

(you'll know how to do that, I trust...)

4./ wait for a mailbox check to happen
- observe the entries in the system log file

(note: if the GSM module was just switched on, and no activity occured on it yet, making it necessary for the server module to provide the PIN code, you might have to wait for a second mailbox check for the message to be delivered).

(when the message is read, switch back to the server console)

5./ server again
- the server process can now be stopped

# killall sms_serv

- exit the script session you started above

# exit
Script done, file is /tmp/sms-server.debug

You can now mail me the .debug file. You could also do an extract of your system log file (/var/log/messages) for the entire test sessions (use timestamps to determine what is relevant). Of course, you can first edit those files to remove any phone / PIN number if you wish. Please remember that the communication is also logged in hex at some point - so please ensure consistency at that level if you decide to edit them.

Generating a debug trace for the CLI client

Please see question 2.3.3 below.

Q2.1.8 Can't get "fast" mode working.

Most likely, this is due to an improperly set "OK string" and/or "line separator" parameter in the driver file (/etc/gsmcaps).

To fix the problem, just run the server in full debug mode (-d option), and compare the hexdumps of modem answers with the "catch phrase list". If they don't match, you got your culprit. Please forward the fix to me (correct OK string and line separator, linked with the exact brand and model of the module), as I might need to release an updated version of the driver file.

Q2.1.9 The "unsupported numplan (...)" message.

Sep 28 16:47:31 kermit sms_serv[3014]: unsupported numplan (85).

In addition, the incoming message triggering this log entry is dropped (i.e. you don't find it in the inbox file, or fed to your filter script).

What happens is as follows. This <numplan> is one of the fields that are to be found in a PDU string. This particular field define the "numbering plan" that the originating GSM number belongs to. Usually, this field is set to either 0x81 (meaning that the originating number is coded as a national number) or 0x91 (indicating an international number). When an international number is found, SMSLink supplies the heading "+" character before storing the record.

Of course, even as 0x81 and 0x91 are the most common, they're not the only ones. As of version 0.54b-8, a few additional numplans are supported, but of course, more will be seen in the wild. For more details on the numplans currently supported by the server, please refer to the PDU format support page.

Should you face this situation, as of version 0.54b-7 of the server, SMSLink offers a way to debug it. Just run the server in debug level "16" (sms_serv -d 16) or full debug mode, of course (-d). This will allow the server to accept any unknown numplan, treat it as indicating a national number, and further process the message. Debug information will be sent to stderr, and a warning will be logged.

When such a message can be successfully processed through this trick, please contact me and give me enough information to include proper support for this numplan in the next release of SMSLink (numplan used, the source it came from, the format of the originating phone number, etc.).

Q2.1.10 The "+CMS ERROR: 515" message.

After switching the SIM card on my development system to a new provider, I started getting +CMS ERROR: 515 error messages each time for the first message I tried to send after a device power-cycle (the error occured at the AT+CNMI=... command). This obviously had something to do with the network login process.

When debugging this further, I noticed a huge increase in the pause time required to process the GSM network sign-on (i.e. what happens "behind the scene" when you switch the device on and provide the PIN code). The required pause was determined to have increased from roughly 20 secs to between 1 and 2 minutes !

So, since this login processing pause obviously could vary from provider to provider, I had to come up with a customizable value, that was provider dependant. I decided to add this parameter to the /etc/gsmdevices configuration file (the "PINpause" parameter).

This parameter is available as of version 0.55b of the server, and its default value, as shipped in the template device line, is still set at 20 secs. When first setting up your SMSLink server, you should try and determine the most suitable value in your case. Here is how you can do it easily.

You first need a properly configured sms_serv(1). Don't worry if sending the first message fails -- just make sure the next one goes through. Then configure your server to use init mode (the last field of your /etc/gsmdevices should look something like, e.g. init,fast). Power-cycle the device to make sure that the PIN code will need to be provided. Then start the server module in full debug mode (./sms_ser -d). Due to the init mode, the server will immediately open a comm. link to the device and initialize it, including the PIN code. If it fails, increase the PINpause value to 120 (I hope this could be considered a reasonable maximum). If it then succeeds, decrease PINpause to half the interval (20 -> 120 = 70) [approach by dichotomy]. If this fails, increase by half the interval. Etc. (you get the picture). Always round the exact result to the next tens, as you have to expect small variations in the pause time.

Q2.1.11 The "sms_serv: lopen_mdm_line() failed: Unknown error" message.

This error isn't thrown by lopen_mdm_line() itself, but by check_for_string() (defined in ./line_manage.c at line 1128, in libmodem's source tree), by the line that reads:

	return & mdm_reply[0];

As indicated by the comment above that line: "No known modem reply found. Return 'Unknown error'", this leads to believe that the GSM device returned some message that libmodem was unable to interpret.

To further debug similar occurences, please refer to question 3.5 below.

Dedicated Daemon issues

Q2.2.1 The "MBC poll missed {...}" message.

Sep 19 09:10:10 kklus011 sms_serv[6619]: initiating mailbox check.
Sep 19 09:10:10 kklus011 sms_serv[6628]: MBC waits for a free GSM instance (pass 1)...
Sep 19 09:10:10 kklus011 sms_serv[6628]: MBC all free GSM's already processed
Sep 19 09:10:10 kklus011 sms_serv[6628]: MBC waits for a free GSM instance (pass 2)...
Sep 19 09:10:10 kklus011 sms_serv[6628]: MBC all free GSM's already processed
Sep 19 09:10:10 kklus011 sms_serv[6628]: MBC poll missed {gsm0}.

Are those the symptom of a serious problem ? Not at all. What they mean is, the mailbox check (the server component generating those messages) can't gain access to any of those devices you configured to use "dd" mode because they're constantly flagged "busy". There wouldn't be any point in polling them anyway, since the whole point of the "dedicated daemon" mode is to get immediate processing of any incoming message on those devices. But if you have any device configured for "poll" mode (default), you most likely need this regular mailbox check. The "MBC poll missed" messages can safely be ignored in this case.

Is there any risk of loosing data ? No. As explained above, the fact that some devices might be missed by the poll is normal behaviour when dealing with devices set to use "dd" mode. Of course, should you notice, in the list of missed devices, one of those that is supposed to be using "poll" mode, you may want to investigate the issue. It is always possible for a device to be missed due to high load on the device at the time. But if the problem persists beyond that period, well, there might be trouble.

Can you get rid of those messages ? The only way to get rid of those messages is to disable the regular mailbox check. How to do that (and whether you might want to do it in the first place) is discussed in the next question.

Q2.2.2 Should I disable the mailbox check ?

If at least one of your devices is in "poll" mode (default), then you'd better leave the mailbox check routine enabled (unless of course you don't care about incoming messages). There will be messages in the log about devices being missed during the poll ("dd"-flagged devices are never marked "free"), but those can be safely ignored (please read previous question regarding this).

To disable the mailbox check edit ./server/sms_serv.h and set MBCHKINTERVAL to 0 (zero), then recompile. As of version 0.55b, a command-line option to that effect will be featured.

Client issues

Q2.3.1 sendsms gives very poor performance.

Q2.3.2 sendsms always fails against a server in "dd" mode.

This problem is a known bug in all versions of the client prior to 0.18b. I failed to notice that the string sent out by the server to signify a successful transmission is different when using "dd" mode. Please upgrade to the latest version of the client.

Q2.3.3 Using script(1) to generate a debug trace for the client.

1./ server
- start a first script

# script /tmp/sms-server.debug
Script started, file is /tmp/sms-server.debug

- start the server in full debug mode

# sms_serv -d

(now just leave it alone, switch to another console)

2./ client
- start a second script

$ script /tmp/sms-client.debug
Script started, file is /tmp/sms-client.debug

- start a client session (in debug mode)

$ sendsms -g -d 1218275172 -m "Test" server-name

- when the client exits, close the second script session

$ exit
Script done, file is /tmp/sms-client.debug

(now switch back to the server console)

3./ server again
- the server process can now be stopped

# killall sms_serv

- exit the first script session

# exit
Script done, file is /tmp/sms-server.debug

You can now mail me both .debug files. You could also do an extract of your system log file (/var/log/messages) for the entire test session, on each machine that was involved in the test if there are more than one (use timestamps to determine what is relevant). Of course, you can first edit those files to remove any phone / PIN number if you wish. Please remember that the communication is also logged in hex at some point - so please, should you choose to edit, ensure consistency at that level.

Integration with third-party software

Q2.4.1 Can I use SMSLink to send Nagios alert messages ?

Of course, you can! That kind of usage was actually one of the main purposes behind the creation of SMSLink.

Here are a few suggested steps you might take to integrate SMSLink with Nagios:

• First, make sure your Nagios server is fully configured and operational.
• Install, configure and test your SMSLink server. The SMSLink server doesn't have to be installed on the same host as the Nagios server, but it can be.
• Install the SMSLink client module, sendsms(1), locally on your Nagios server. Make sure it is installed somewhere along the PATH and that it can reach the SMSLink server host.
• Add the following entries in Nagios misccommands.cfg file:

  # 'notify-by-SMS' command definition
  define command{
  	command_name	notify-by-SMS
  	command_line	/usr/local/bin/sendsms -d $CONTACTPAGER$ \
  	-m "$SERVICESTATE$ alert for $HOSTALIAS$/$SERVICEDESC$" localhost
  	}
  
  # 'host-notify-by-SMS' command definition
  define command{
  	command_name	host-notify-by-SMS
  	command_line	/usr/local/bin/sendsms -d $CONTACTPAGER$ \
  	-m "Host '$HOSTALIAS$' is $HOSTSTATE$" localhost
  	}
  

  Feel free to modify the actual message contents to suit your needs, of course.
• I recommend you create a new contact group (edit contactgroups.cfg) that will contain only contacts (i.e. people) to be reached by SMS. I called it SMSworthy.
• Create at least one contact profile to be put in the new SMSworthy group. Don't forget to specify the target GSM number as the pager parameter. The service_notification_commands and host_notification_commands parameters should be set to notify-by-SMS and host-notify-by-SMS respectively.
• Then, associate the new contact group (SMSworthy) with some host groups (edit hostgroups.cfg) and/or services (edit services.cfg). I recommend attaching the SMS notification method only to critical hosts and/or services on your network.
• When done, restart Nagios.

Hardware-related questions

Q3.1 Using a multi-serial board / more than 2 serial ports

But of course, some situations might require the use of specific hardware allowing one to drive a lot more than 2 serial devices (such as through the use of multi-serial boards). SMSLink is perfectly equiped to handle that. The only think you'll have to do is make sure, before you compile the server, to edit server/sms_serv.h and alter the value of MAXMODEMS to reflect the (projected maximum) number of serial devices you will want to connect to the server.

To repeat myself, this maximum number of devices doesn't have to be reached from the start. The only use of this value is to provide some form of sanity check for the devices configuration file (by default, /etc/gsmdevices), to avoid an unreasonable amount of devices being defined by mistake. It should basically reflect the maximum amount of (external) serial devices your hardware is able to support.

Q3.2 Hardware or software flow control.

It looks like that FreeBSD works better with software flow control (XON-XOFF) than with hardware. In Stanley's own words:

--------------------------------------------------
The last note is that the message loss with hardware flowcontrol set
in /etc/modems is worse than XON/XOFF. Message loss begins when the
message rate exeeds 12/min (ie 5 seec between messages) rather than
about 30 messages/min with XON/XOFF.

I think this suggests that FreeBSD does not have a termios or whatever
that supports hardware flow control (from man termios

The CCTS_OFLOW (CRTSCTS) flag is currently unused

)
--------------------------------------------------

Hence, make sure that CTSRTS support is in the kernel, and that you enabled it on the "sio" serial driver.

Q3.3 Handling devices that don't support flow control

  I had some issues with the Ericsson GM-12 which supported *nothing*
  beyond the two data wires and ground (from memory). i.e. If your tty
  settings had the machine waiting for DCD or CTS (or what ever) you
  would never see them. The standard libmodem doesn't seem to support
  that directly - it wants either software or hardware flow control.

  In the end I think I just used minicom to switch off *all* flow control and
  quit minicom with out restoring the settings. Then used software flow
  control and hoped that the SMS never sends ^S/^Q. It seems to work fine....

In a later email, Andrew was kind enough to give more details on the way to accomplish this (and the reasoning behind):

  minicom stuff: 

   Ctl-A Z  - to get the menu, not necessary 
   O        - Get the configuration
   Down arrow to select "Serial port setup" with Return key 
   set "Hardware Flow Control" and "Software Flow Control" to "No" 
   by toogling with the F and G keys. 

   Return         - get out of configuration menu 
   Q              - Quit with out reset (leave the parameters as set) 
   Return         - When it prompts do you really want to quit with out reset. 


  The GM-12 modem is just dumb - so no init strings will be able to 
  persuade the modem to start doing flow control (it doesn't have the wires 
  for it anyway :-). My minicom stuff is setting up the tty driver in the 
  Linux box to stop the Linux box expecting any flow control. 

Q3.4 The "+CMS ERROR: 514" message

Syntax error in command:
The first and most obvious one is that the command that triggered the error message contained a syntax error. The only command likely to trigger it is "AT+CMGS=..." (the one that sends the SMS). When faced with the message, you might want to first check the user's guide for your module to see whether the syntax of this command was perhaps modified.

As a slight variation around the previous note, the internal structure of a PDU string, when incorrect, can also trigger that message if my memory serves. To rule that out, you might want to try and see whether the error also appears when sending text-mode (if supported by your device, of course).

Hardware problems preventing network connection:
Here are a few suggestions David Martinez added to this issue, pointing in the direction of a hardware problem preventing the module from logging in on the GSM network:

• maybe the SCA (aka SMSC) either is incorrect or is not present;
• maybe the antenna is not the proper one for the device (for instance, dual-band models such as the WMOD2B need a dual-band antenna);
• maybe the power supply is not strong enough (the device will attempt to draw a lot more power from its PS when the network signal is weak and it has to be amplified). This would show specifically when doing dial or SMS sending operations.

All of those conditions might cause the error 514 that we experienced.

SIM card failure:
And finally, here is something I noticed recently, when using a new SIM card for the first time (this is actually what prompted my question to David in the first place): some (most ?) SIM cards are not "active" as soon as you purchase them. You have to place at least one regular call for the provider network to "register" you. Before this is done, don't even think of sending an SMS. You are attached on the network all right (as reported by the "AT+CREG?" command), but you don't have access to all its services.

Q3.5 Manually sending an SMS to debug the modem replies

When you need to add support for a new device and its manual is not really clear on how the modem should respond to certain stimuli, or to help you debug a "sms_serv: lopen_mdm_line() failed: Unknown error" error message, you may want to manually send your modems the AT commands it needs to send an SMS.

Here below is a step-by-step procedure detailing how you can do just that.

• Fire-up minicom (make sure no other process is locking your GSM device -- if sms_serv is running, stop it).
• First make sure minicom is correctly setup to interact with your device (are you able to issue simple commands ?). If not, correct your setup.
• At this stage, you want to enable minicom's logging feature (you can then send me the log trace later on). To do this, press Ctrl-A L.
• Then proceed with the SMS sending procedure.
• Set GSM to "verbose" error reporting mode
  AT+CMEE=1
• Check for SIM status
  AT+CPIN?
• (if "READY" => OK, if "SIM PIN", then provide it)
  AT+CPIN="xxxx" (where "xxxx" is your PIN code, obviously)
• (you have to wait here for the GSM network to process your login request -- from 20 secs. to up to 2 min.)
• Set "no notify for incoming SMS messages"
  AT+CNMI=0,0,0,0,0
  warning: the format of this command varies much from device to device -- check your user guide if required.
• Check stored SCA against requested SMSC
  AT+CSCA?
• if not correct, set it (use the SMSC recommended by your provider)
  AT+CSCA="........"
• Check stored mode against requested mode
  AT+CMGF?
• if the reply isn't to your taste, set it with
  AT+CMGF=x
  (x = 0 for PDU, x = 1 for text mode)
  Note: If supported by your device, please use text mode !
• Am I registered on the network ?
  AT+CREG?
  A successfull reply looks like "+CREG:0,1" or "+CREG:0,5". If you got that, go ahead (otherwise, no point).
• Now actually send SMS message
  AT+CMGS="........." ("..." = destination GSM number)
  "message"
  ^Z
• the device should reply with the outgoing message ID.