NOTE for users running smsd with very heavy load

Current version of smsd moves files between spooler directories using the original file name. If outgoing files are created using a fixed filename (which is not recommended) and lot of files using the same name are created within a short period, it's possible that previous file and it's .LOCK file are still existing in the spooler directory. In this case a new file cannot be moved to the spool. Previously the smsd stopped with a fatal error in this case. Now an alarmhandler is called and after it has returned a file moving is retried. If a file still cannot be moved, the smsd will stop with a fatal error.

The alarmhandler can be used to help with a file moving conflict. The script can wait until a spooler can be used, or it can wait some fixed time like 5 seconds. It can also produce some notices to the administration, if necessary.

In some cases this kind of conflict is a result of a previously happened error in the system which creates outgoing files to send. In this case it's better to let smsd stop, instead of sending couple of thousand messages to somewhere...

In the conflict case the alarmhandler will get following arguments (as an example):

• $1=ALARM
• $2=2007-07-06
• $3=12:00:00
• $4=2
• $5=smsd
• $6=Conflict with .LOCK file in the spooler: /var/spool/sms/outgoing/test_file /var/spool/sms/checked

Running (as a root)

IMPORTANT: The smsd inherits it's priviledges from the user who started the daemon. If starting is done by the root or system startup, priviledges of root are inherited. In this case the smsd can switch to the unpriviledged user account, if it is defined in config file or command line (in the sms3 script). If the smsd is started by the unpriviledged user, account switching is not available.

Easiest way to run the smsd is running it as a root:

Method 1 (recommended for the normal use):

Enter /etc/init.d/sms3 start to start smsd in background.
Enter /etc/init.d/sms3 stop to stop smsd.

NOTE: On some installations (Debian, Ubuntu for example) script is using name smstools.

In case of Unix, you might create links in your runlevel directories (for example /etc/rc3.d or /etc/init.d/rc3.d) if the program shall start and stop automatically together with the operating system.

With sms3 script you can ensure that:

• If smsd is already running, duplicate daemon is not started.
• When smsd is stopped while it is sending a multipart message, the script will wait until all parts are sent. Information of the process is printed to terminal, so you can see why the daemon is not stopped immediately.
• In case of troubles there is force-stop argument available. This handles all smsd processes, not just the main process.

NOTE: When the smsd main process receives a termination signal, it sends it to all subprocesses. After a signal is received, no more new jobs are started. Already started jobs are completed, which usually will not take too much time.

NOTE: If you are running smsd in heavy traffic environment, and you OS does not wait processes while it is shutting down, it is recommended to stop the smsd with /etc/init.d/sms3 stop before shutting down the OS.

Method 2:

Run /usr/local/bin/smsd -s to start the program in a command window.
The smsd will run in foreground and status monitor is printed to terminal.
Press Ctrl-C to stop the program.

Method 3:

Enter /usr/local/bin/smsd to start the daemon in background.
Enter pkill smsd to stop it.

Running smsd as an unpriviledged user

In some environments it is more suitable to run smsd with priviledges of a standard user. There are two ways to do this:

• Recommended way: Define user account settings in sms3 script and use it to start the smsd by the root.
• Start the smsd by the unpriviledged user.

In both cases you must ensure that infofile and pidfile are writable by the unpriviledged user. Location and name of those files can be defined in the config file, if sms3 script is not used. Most recommended way is using the sms3 script, and change settings in this script.

In the sms3 script there are settings USER="" and GROUP="".
Usual settings for these are the same group and user who owns the modem device, for example USER="uucp", GROUP="dialer" or USER="smsd", GROUP="dialout". Selected user must have write permissions to the device(s).

Selected user must also have write permissions to the spool directories. For example those directories can be owned by this user. Other users who are permitted to send messages should have write permissions to the outgoing directory.

infofile and pidfile should be moved to the place which is writable by the selected user, for example:
PIDFILE="/var/run/smsd/smsd.pid" and
INFOFILE="/var/run/smsd/smsd.working"

Usually the default logfile is not writable by the unpriviledged user, this should be defined in the sms3 script too:
LOGFILE="/var/log/smsd/smsd.log"

When the smsd is trying to start, all permissions and availability of directories are checked. If there are any problems, they are reported and smsd shuts down. This prevents problems in the future, for example when smsd was run for couple of days and failed directory is first time needed. If a directory is not accessible, smsd stops.

Sending a message

Run the command sendsms 491721234567 'Hello, how are you' to send a message or put an SMS file into the Outgoing Folder /var/spool/sms/outgoing.

To read a received message, take a look into the Incoming Folder /var/spool/sms/incoming.

Using a Regular Run feature (version >= 3.1)

After version >= 3.1 it is possible to define an external regular_run script or program in the configuration file. This program or script is executed at a given interval while the smsd is running. Because the smsd controls when the script is executed, there is no need to start/stop procedures like using traditional crontab. In the future versions there will also be some return value handling. Currently return values other than zero are reported to the log file.

This example is about verifying the delivery of a sent message. If it's not delivered fast enough, a same message is sent to the alternate phone number.

When the first message is sent:

• There is To: field for primary number.
• There is also Alternate_to: field for an alternate number. The smsd does not use this field by itself.
• Status report is requested: Report: yes (or smsd.conf report = yes).
• The smsd adds Sent: timestamp and Message_id: nr fields automatically to the sent message file.

When a status report is received, it's stored to the incoming folder as described in the SMS file format. An eventhandler can find the relevant sent message and add the Received: timestamp header to the message file.

If a destination phone is switched off, or it's out of GSM network, the status report is not received, of course because the message is not delivered.

• Alternate_to number is taken to the memory and removed from the first message.
• The modified first message is copied to the temp.
• To number in the temp message is replaced with a number which was an alternate to.
• A temp message is moved to the outgoing folder.

See smstools3/scripts/regular_run script for more details. This script is compatible with ASCII messages with character set ISO or GSM. This kind of functionality can also be made with MySQL, but this example is file based.