SMS Server Tools 3

Home

Configuring

Please note that the book describes this topic with more details.

The config file is /etc/smsd.conf. You may specify another file using the option -c. During installation an easy example file will be copied to smstools3/examples directory.

The config file has the following structure:

some global settings

[first modem name]
...
[second modem name]
...
[third modem name]
...
and so on

I left out the part for the provider-sorting feature.

In case of yes/no settings, you can use the following keywords:

yes , no
true , false
on , off
1 , 0

In case of lists, you need to use the comma character to separate items. Example: modem1, modem2, modem3

Global part

The global part begins at the top of the config file.

devices = names
List of names of your modems, maximum 32 devices. This limit is changeable.

outgoing = directory
Path of the Outgoing Queue folder.

checked = directory
Path of the default Queue directory in case you do not use provider-sorting.

failed = directory
Path of the Failed Folder. Delete this line if you do not want to keep failed files.

incoming = directory
Path of the Incoming Folder.

report = directory
Available from version >= 3.1. Path of the Report Folder. Without this setting status report messages are stored to the Incoming Folder.

sent = directory
Path of the Sent Folder. Delete this line, if you do not want to keep copies of each sent message file.

mypath = directory
Specifies the directory where you installed the SMS Server Tools binaries. Default is /usr/local/bin.
This setting is not used in > 3.0.1 versions.

logfile = filename
Name of the log file. Delete this line, if you want to use the syslog for logging. You can use "1" to write to the console (stdout).
This setting can be overridden by the -l (ell) command line argument.

loglevel = number
Sets the verbosity of your log file. The default is "4" if you use a logfile and it is "7" if you use syslog.

This affects also syslog. If you want all messages in syslog, you need to set it to "7" (or higher) here and "*" in the config file of syslog. If you want less messages, you can reduce it here or in the config file of syslog, both will work.

debug7All AT-Commands and modem answers and other detailed informations useful for debugging
info6Information what is going on at the moment. Not detailled enough for debugging but maybe interesting.
notice5Information when a message was received or sent and when something not normal happens but program still works fine (for example wrong destination number in SMS file).
warning4Warning when the program has a problem sending a single short message.
error3Error message when the program has temporary problem (for example modem answered with ERROR during initialization or a file can not be accessed).
critical2Error message when the program has a permament problem (for example sending failed many times or wrong permissions to a queue).
The numbers in this table are taken from Linux. I think that all operating systems use the same numbers, but I'm not 100% sure.

alarmhandler = filename
You can specify here an external program that is started whenever an alarm occurs.

alarmlevel = number
Specifies what levels start an alarmhandler. You can use value between 2 and 5.

delaytime = number
Smsd sleep so many seconds when it has nothing to do.

errorsleeptime = number
A modem sleeps so many seconds when it answers a command with ERROR.

blocktime = number
A modem is not used so many seconds when it seems to be out of order.

blockafter = number
Available from version >= 3.1. Default value is 3. A modem is blocked after n number of errors while sending messages. A successfull sending will reset this counter.

eventhandler = filename
Specifies an external program or script that will execute whenever a message was sent, received or failed.
(If your locale is UTF-8, you can use this script to convert received messages from smsd's internal format (ISO) to UTF-8. See scripts/eventhandler-utf-8 for code sample.)
After version >= 3.1 there is incoming_utf8 = yes setting available. Using this setting the external conversion is not required.

stats = directory
Specifies the directory where smsd stores statistic files. The directoy must exist before you start smsd. If not given, then the program does not write statistic files.

stats_interval = number
Smsd writes statistics files every n seconds. I would recommend 3600 for 1 hour.

stats_no_zeroes = yes/no
Smsd does not write statistic files when no message was sent or received (Zero-Counters) if this is set to yes. Default is no.

blacklist = filename
Name of the blacklist file.

whitelist = filename
Name of the whitelist file. The black list takes precedence before the white list. See Blacklist and Whiteliste for more details and sample usage.

checkhandler = filename
External program that checks if a message file is valid. (This script can also be used to convert message file from UTF-8 to ISO format, which is internal format used in smsd. See scripts/checkhandler-utf-8 for sample code.)
After version >= 3.1 the smsd converts messages automatically from UTF-8 to ISO, if it is necessary.
If the checkhandler return a non-zero (other than 2) exitcode the message will not be sent.
With the smsd version >= 3.1 the checkhandler can also modify a message file.
Exitcode 2 means that the checkhandler has moved a message to the spooler by itself.

autosplit = number
Controls if and how the program splits large text messages. The program does not split binary messages, Unicode messages and text messages with UDH.
0disabled
1enabled, no part-number
2enabled, text numbers
3enabled, concatenated format (not supported by some phones)

receive_before_send = yes/no
Forces smsd to empty the first SIM card memory before sending SM. This is a workaround for modems that cannot send SM with a full SIM card.

store_received_pdu = number
Available from version >= 3.0. Controls when the incoming PDU string is stored to message file.
0no PDU's are stored
1unsupported PDU's are stored (default)
2unsupported and PDU's with 8bit binary data or unicode text are stored
3all PDU's are stored
Header is "PDU: " and PDU's of a multipart message are stored from 1 to n order.

validity = number
Available from version >= 3.0. See SMS file for details of possible values.

decode_unicode_text = yes/no
Available from version >= 3.0. Controls when the incoming unicode text is decoded internally.

internal_combine = yes/no
Available from version >= 3.0. Controls when the incoming multipart message is combined internally.

Next four settings are available from version >= 3.0.2:
user = username
group = groupname
If the smsd is started by the root, these two settings can be used to switch smsd to run as an unpriviledged user.
infofile = filename
pidfile = filename
Location of infofile (by default /var/run/smsd.working) and pidfile (by default /var/run/smsd.pid) can be changed with these settings. This is usually necessary if the smsd is running as an unpriviledged user. If a sms3 script is used to start and stop the smsd, these settings should be defined in the script.
These four settings can be overridden by the command line argument(s):

See Running for more information.

keep_filename = yes/no
Available from version >= 3.1. Default value is yes. If this is set to no, an unique filename is created each time when a message file is moved from directory to another directory. This ensures that any previously sent message file is not overwritten, even if the original filename was the same. Also if an user has created filename with space character, this creates a new name without spaces and therefore spaces can't effect to operation of an eventhandler..

store_original_filename = yes/no
Available from version >= 3.1. Default value is yes. Together with keep_filename this controls when the original filename is stored to message file when it's moved from outgoing directory to the spool.

regular_run = filename
regular_run_interval = number
Available from version >= 3.1. A regular_run is an external script or program which is run regularly while the smsd is running. A value regular_run_interval describes number of seconds between each run. Default value for this is 5 minutes.
See Running for more information and sample usage.

admin_to = phone number
Available from version >= 3.1. Specifies a destination number for administrative messages created by smsd.

terminal = yes/no
Available from version >= 3.1. Enables terminal mode like command line argument -t.

filename_preview = number
Available from version >= 3.1. Defines how many characters of message text is concatenated to the name of a messsage file. Currently works with incoming message files. Characters used are a...z, A...Z, 0...9, - and period. All other characters are replaced with _'s.

incoming_utf8 = yes/no
Available from version >= 3.1. With this setting messages using ISO or GSM alphabet are stored using UTF-8 character set.


Modem settings

[modem name]
Begin of a modem settings block. The modem name must be the same as in the devices= line in the global part.

init = modem command
Specifies a modem initialisation command. Most modems do not need any init string. See the manual of your modem for more details of modem commands.

init2 = modem command
Specifies a second modem initialisation command. Most users do not need this.

device = name of serial port
Specifies the device name of the serial port to the modem. Linux example: /dev/ttyS0. Windows example: /dev/com1. Solaris example: /dev/cuaa.

incoming = no/yes/high or 0/1/2
Specifies if the program should read incoming SM from this modem. "Yes" or "1" means that smsd receives with less priority. The value "high" or "2" means that smsd receives with high priority. "No" or "0" means that smsd does not receive messages.

memory_start = number
Tells the first memory space number for received messages. This is normally 1, Vodafone Mobile Connect Card starts with 0.

queues = list of queue names
Specifies the Provider Queues that this modem shall serve. Use the same provider names as in [queues] and [provider]. If you do not use the provider-sorting feature, then leave this line out.

pin = 4 digit number
Specifies the PIN number of the SIM card inside the modem. Delete this line, if your computer does not need to enter a PIN. See also pinsleeptime.

mode = old/new
Specifies version of modem command set. Almost everybody needs to set it to "new" which is the default.

oldfor Falcom A1 and maybe some other old modems of GSM phase 1 (1990-1995)
newfor nearly all mobile phones and modems

smsc = number
Specifies the SMSC number that this modem should use to send SM. You need this setting only if the default of the SIM card is bad. Write the phone number of the SMSC in international format without the starting "+".

baudrate = number
Specifies the speed of the serial communication in bits per second. Most modems work well with 19200 baud, some need 9600 baud.

rtscts = yes/no
You can disable usage of hardware handshake wires by setting this option to "no". Please don't use this feature in commercial applications because the hardware handshake wires ensure proper communications timing between the computer and the modem.

send_delay = number
If your modem does not support hardware handshake you should use the lowest possible baudrate to ensure that the program does not run faster than the modem can do. However, if the lowest possible baudrate is still to fast, then you can use this parameter to make it even slower. A value of 300 means that the program waits 300 milliseconds between sending each single character to the modem. This makes the program very slow. Default value of send_delay is 1 millisecond.

cs_convert = yes/no
The program converts normal text messages into GSM character set. You need this to display german umlauts and control characters correctly.

report = yes/no
If you enable this, the program requests a status report SM from the SMSC for each sent message. This does not work on many mobile phones and on some modems.

eventhandler = filename
Specifies an eventhandler script like in the global part. If you use this variable, then this modem will use its own individual eventhandler instead of the global one.

primary_memory = memory name
secondary_memory = memory name
secondary_memory_max = number
These three settings are used to control dual-memory handler, available from version >= 3.0.
If your modem/phone receives messages to the Mobile Equipment (ME) memory after the SIM memory (SM) has been filled up, with dual-memory handler messages can be read from the Mobile Equipment memory too.
Defining secondary_memory_max is needed, if your device does not tell how much there is space in the Mobile Equipment memory. For example the Nokia 6210 does not tell (it returns 0 as max value) and with this device 150 is reasonable value.

pdu_from_file = filename
Available from version >= 3.0. This is for testing purposes.
You can test you eventhandler and some other things without actually receiving a message from the modem/phone. This is especially important when it's not possible to receive the same message again because the sender cannot be reached.
You may have the original PDU string stored to the incoming messsage file, or you may see it in log file (depending of the loglevel). This PDU string can be stored to the pdu_from_file named file, and when this file exists the smsd will read the PDU from there. Rest processing will be done similarry than with normally received messsages and you can then debug possible problems and see when they are fixed.
This file can contain empty lines and comment lines starting with # character.
Actual data can be stored as one line containing the PDU string, or two lines containing (first) the modem answer and (second) the PDU string.
For example:
#2006-09-13 13:12:10,7, GSM1: <-
+CMGR: 0,,40
0791531811111111240C9153183254769800F1609031314174211854747A0E4ACF416110BD3CA783DAE5F93C7C2EBB14

or simply one line only:
079153181111111106BC0C91531832547698609031314174216090313141842100

NOTE: After this file is processed, it is removed.

sending_disabled = yes/no
Available from version >= 3.0. This is for testing purposes.
You can test your eventhandler and whole system around the smsd without sending any messages to the GSM network. All other functionality is working as usual, so this is some kind of "mute" to the modem. However the modem should be connected and working. This does not have an effect to the incoming messsages.

decode_unicode_text = yes/no
Available from version >= 3.0. Specifies an internal unicode decoding like in the global part.

internal_combine = yes/no
Available from version >= 3.0. Specifies an internal multipart message combining like in the global part.

pinsleeptime = number
Available from version >= 3.1. Specifies how many seconds the program will sleep after a PIN is entered. Some modems do not work without some delay.

admin_to = phone number
Available from version >= 3.1. Specifies a destination number for administrative messages created by smsd. This setting overrides the setting in the global part.

message_limit = number
message_count_clear = number
Available from version >= 3.1. Message_limit specifies the maximum number of messages to send. After this limit is reached, no more messages will be sent until the smsd is restarted or message counter is cleared by the message_count_clear setting. The value of this setting is minutes.
If admin_to is specified, an administrative message is sent when the limit is reached.

outgoing = yes/no
Available from version >= 3.1. Default value is "yes". Specifies if a modem is used to handle and send outgoing messages.