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 |
Configuring the provider-sorting is shown in different document.
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
The global part begins at the top of the config file.
devices = names
Default value: empty.
List of names of your modems, maximum 32 devices. This limit is changeable.
outgoing = directory
Default value: /var/spool/sms/outgoing.
Path of the Outgoing Queue folder.
checked = directory
Default value: /var/spool/sms/checked.
Path of the default Queue directory in case you do not use provider-sorting.
failed = directory
Default value: not in use.
Path of the Failed Folder. Delete this line if you do not want to keep failed files.
incoming = directory
Default value: /var/spool/sms/incoming.
Path of the Incoming Folder.
report = directory
Default value: not in use.
Available from version >= 3.1. Path of the Report Folder.
Without this setting status report messages are stored to the Incoming Folder.
sent = directory
Default value: not in use.
Path of the Sent Folder. Delete this line, if you do not want to keep copies of each sent message file.
logfile = filename
Default value: empty.
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
Default value: 4 for logfile, 7 for syslog.
Sets the verbosity of your log file.
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.
debug | 7 | All AT-Commands and modem answers and other detailed informations useful for debugging |
info | 6 | Information what is going on at the moment. Not detailled enough for debugging but maybe interesting. |
notice | 5 | Information 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). |
warning | 4 | Warning when the program has a problem sending a single short message. |
error | 3 | Error message when the program has temporary problem (for example modem answered with ERROR during initialization or a file can not be accessed). |
critical | 2 | Error message when the program has a permament problem (for example sending failed many times or wrong permissions to a queue). |
alarmhandler = filename
Default value: not in use.
You can specify here an external program that is started whenever an alarm occurs.
After version >= 3.1 a value can be defined as a word, like LOG_INFO, INFO or info.
alarmlevel = number
Default value: LOG_WARNING.
Specifies what levels start an alarmhandler. You can use value between 2 and 5.
delaytime = number
Default value: 10.
Smsd sleep so many seconds when it has nothing to do.
errorsleeptime = number
Default value: 10.
A modem sleeps so many seconds when it answers a command with ERROR.
blocktime = number
Default value: 3600.
A modem is not used so many seconds when it seems to be out of order.
blockafter = number
Default value: 3.
Available from version >= 3.0.9.
A modem is blocked after n number of errors while sending messages.
A successfull sending will reset this counter.
eventhandler = filename
Default value: not in use.
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.0.9 there is incoming_utf8 = yes setting available.
Using this setting the external conversion is not required.
stats = directory
Default value: not in use.
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
Default value: 3600.
Smsd writes statistics files every n seconds.
stats_no_zeroes = yes/no
Default value: no.
Smsd does not write statistic files when no message was sent or received (Zero-Counters) if this is set to yes.
blacklist = filename
Default value: not in use.
Name of the blacklist file.
whitelist = filename
Default value: not in use.
Name of the whitelist file. The black list takes precedence before the white list.
See Blacklist and Whitelist for more details and sample usage.
checkhandler = filename
Default value: not in use.
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.0.9 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
Default value: 3.
Controls if and how the program splits large text messages.
The program does not split binary messages and text messages with UDH.
0 | disabled |
1 | enabled, no part-number |
2 | enabled, text numbers (with Unicode value 3 is used) |
3 | enabled, concatenated format (not supported by some phones) |
receive_before_send = yes/no
Default value: 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
Default value: 1.
Available from version >= 3.0. Controls when the incoming PDU string(s) is stored to message file.
0 | no PDU's are stored |
1 | unsupported PDU's are stored |
2 | unsupported and PDU's with 8bit binary data or Unicode text are stored |
3 | all PDU's are stored |
validity = number
Default value: 255.
Available from version >= 3.0. See SMS file for details of possible values.
decode_unicode_text = yes/no
Default value: no.
Available from version >= 3.0. Controls when the incoming Unicode text is decoded internally.
internal_combine = yes/no
Default value: 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
Default value: not in use.
group = groupname
Default value: not in use.
If the smsd is started by the root, these two settings can be used to switch smsd to run as an unpriviledged user.
As of version >= 3.0.9, if user is set but group is unset, that user's normal groups (e.g. from
/etc/groups) are used.
This means you can allow other users on the system access to write messages to the outgoing spool without giving them
direct access to the serial port.
infofile = filename
Default value: /var/run/smsd.working.
pidfile = filename
Default value: /var/run/smsd.pid.
Location of infofile and pidfile 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):
keep_filename = yes/no
Default value: yes.
Available from version >= 3.1. 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
Default value: yes.
Available from version >= 3.1. 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
Default value: not in use.
regular_run_interval = number
Default value: 300.
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.
See Running for more information and sample usage.
admin_to = phone number
Default value: not in use.
Available from version >= 3.1. Specifies a destination number for administrative messages created by smsd.
terminal = yes/no
Default value: no.
Available from version >= 3.1. Enables terminal mode like command line argument -t.
filename_preview = number
Default value: not in use.
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
Default value: no.
Available from version >= 3.0.9. With this setting messages using ISO or GSM alphabet are stored using UTF-8 character set.
log_charconv = yes/no
Default value: no.
Available from version >= 3.0.9.
With this setting a details of character set conversions (outgoing UTF-8 to ISO conversion and incoming GSM/ISO to
UTF-8 conversion) is printed to the log.
If smsd is compiled using DEBUGMSG definition, details are also printed to the console.
Logging feature can be useful if you have some troubles with characters and like to know what exactly happens inside the smsd.
store_sent_pdu = number
Default value: 1.
Available from version >= 3.0.9. Controls when the outgoing PDU string(s) is stored to message file.
0 | no PDU's are stored |
1 | failed (to send) PDU's are stored |
2 | failed and PDU's with 8bit binary data or Unicode text are stored |
3 | all PDU's are stored |
os_cygwin = yes/no
Default value: no.
Available from version >= 3.0.10.
Defines if smsd is running on Cygwin environment.
This is needed if outgoing file permissions should be checked and changed by the smsd.
[modem name]
Begin of a modem settings block. The modem name must be the same as in the devices= line in the global part.
pre_init = yes/no
Default value: yes.
Available from version >= 3.0.8. Specifies is an "echo off" and "CMEE=1" commands are sent to the modem
before anything else is done.
init = modem command
Default value: not in use.
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
Default value: not in use.
Specifies a second modem initialisation command. Most users do not need this.
device = name of serial port
Default value: empty.
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
Default value: no.
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
Default value: 1.
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
Default value: not in use.
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
Default value: not in use.
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
Default value: new.
Specifies version of modem command set.
Almost everybody needs to use this as a "new".
From version >= 3.0.9 this effects mainly to the sending side. In the receiving side the incoming PDU is checked, and if it does not match to the selected mode, another mode is tried automatically.
old | For Falcom A1 and maybe some other old modems of GSM phase 1 (1990-1995). In the receiving side this mode does not have SCA information in the begin of PDU. |
new | For nearly all mobile phones and modems. In the receiving side this mode has SCA information in the begin of PDU. |
smsc = number
Default value: not in use.
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
Default value: 19200.
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
Default value: yes.
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
Default value: 1.
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
which makes the program very slow.
cs_convert = yes/no
Default value: yes.
The program converts normal text messages into GSM character set. You need this to display
german umlauts and control characters correctly.
report = yes/no
Default value: 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
Default value: empty.
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
Default value: not in use.
secondary_memory = memory name
Default value: not in use.
secondary_memory_max = number
Default value: accept what device returns.
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 / directoryname/
Default value: not in use.
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.
After >= 3.0.9 the setting can be a directory.
If this setting ends with a slash and a directory with that name exists,
file(s) are read from this directory (and deleted after processing).
All files found from the given directory are processed one by one, expect hidden files (name begins with a dot).
When this setting points to the directory, no dot's are allowed in any position of a path.
Be very careful with this setting while it will delete the content of a whole directory.
After >= 3.0.9: while reading a PDU from file, a first line starting with PDU: and space is taken if any exists.
sending_disabled = yes/no
Default value: 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.
modem_disabled = yes/no
Default value: no.
Available from version >= 3.0.9. This is for testing purposes too.
Whole messaging system including eventhandlers etc. can be tested without any working
modem existing. Sending of messages is simulated in the similar way than with sending_disabled setting.
Incoming messages are taken only from the file, if pdu_from_file is defined.
No any communication is made between smsd and modem, but a device setting should still exist because smsd wants to
open and close a device.
If in you testing environment you do not have a priviledges to the usual modem device,
like /dev/ttyS0, you can use a definition like device = /tmp/modemfile.
If this file exists and is writable for the process owner, it's enough for smsd.
decode_unicode_text = yes/no
Default value: use the global part setting.
Available from version >= 3.0. Specifies an internal Unicode decoding like in the global part.
internal_combine = yes/no
Default value: use the global part setting.
Available from version >= 3.0. Specifies an internal multipart message combining like in the global part.
pinsleeptime = number
Default value: 0.
Available from version >= 3.0.9. 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
Default value: not in use.
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
Default value: not in use.
message_count_clear = number
Default value: not in use.
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
Default value: yes.
Available from version >= 3.0.9.
Specifies if a modem is used to handle and send outgoing messages.