Name

Synopsis

Description

This manual page will cover the functionalities and use of sms_serv. For installation and configuration instructions, please refer to the INSTALL document, provided in the sources directory.

Options

-cn, --mbchkinterval=n

Sets the incoming message box check interval to n seconds. Overrides the compiled-in default stored in the "MBCHKINTERVAL" macro defined in server/sms_serv.h. A value of 0 (zero) disables the mailbox check completely. Acceptable values for the interval range from 60 (= 1 min.) to MAXINT. Compiled-in default as shipped: 3600 secs (= 1 hour).

-on, --obchkinterval=n

Sets the outgoing message box check interval to n seconds. Overrides the compiled-in default stored in the "OBCHKINTERVAL" macro defined in server/sms_serv.h. A value of 0 (zero) disables the outbox check completely (no message queuing can take place through the server in this case). Acceptable values for the interval range from 60 (= 1 min.) to MAXINT. Compiled-in default as shipped: 0 secs (= feature disabled).

-ln, --obchklimit=n

Limits the number of queued messages that will be processed per queue run to n (unlimited by default). Setting this value to 0 means "unlimited".

-rn, --maxqruns=n

Specifies the life expectancy of queued messages. Any queued message will be processed at most maxqruns times. In case delivery is still unsuccessfull after the last attempt, the queued message is removed and a bounced-back mail message is sent to the administrator (since the email address of the sending user isn't known). The email address of the administrator can be configured through the -b option.

-qs, --qmethod=s

Selects the queueing method (aka backend). Acceptable values for s are file, db and none. The file method means that queued messages will be stored as files on the filesystem (by default, in the /var/spool/smslink/outbox directory, this can be changed through the OBOX_SPOOL define). This method (which is enabled by default) doesn't require any other configuration item (save for the existence of the spool directory). The db method means that queued messages will get stored as records in a backend MySQL database. See the -D, -B, -u and -k options and the gsmdbtab (5) file for details on how to enable database access. Setting qmethod to none disables queueing altogether.

-Xs, --exec=s

Sets the name of the external program or script that will get called during inbox runs to process incoming messages. The call to this program will be made only if the prog option flag is selected in your gsmdevices(5) configuration file.

-Ds, --dbhost=s

Specifies the name of the server where the database lives. Use of this option will override any conflicting value found in the database credentials file (see gsmdbtab(5) for the format of that file).

-Bs, --dbname=s

Specifies the name of the database instance you want to connect to. Use of this option will override any conflicting value found in the database credentials file (see gsmdbtab(5) for the format of that file).

-us, --dbuser=s

Specifies the username you want to use to connect to the database. Use of this option will override any conflicting value found in the database credentials file (see gsmdbtab(5) for the format of that file).

-ks, --dbpass=s

Specifies the password of the user you want to use to connect to the database. For obvious security reasons, it is highly recommended NOT to use this option to specify the password. Use of this option will override any conflicting value found in the database credentials file (see gsmdbtab(5) for the format of that file).

-is, --pidfile=s

Uses the provided string as name for the PID file. By default, the PID file name would be /var/run/sms_serv.pid. In case the filesuffix option is used in conjunction with this one, the requested file suffix is appended to the specified PID file as well.

-fs, --filesuffix=s

Will append the provided string as a suffix to all site-specific configuration files, namely /etc/gsmdevices, /etc/gsmaccess and /etc/gsmdbtab. The suffix will also be appended to the PID file name. A leading dot will automatically be added to the provided file suffix.
Used in combination with the --port option, this allows you to run multiple instances of the server module on the same host, each instance using its own set of configuration files.

-pn, --port=n

Specifies a non-standard port for the server to bind its socket to. Overrides the value that should otherwise be picked from the one defined in the /etc/services file. This option can be very handy when you want to run the server as a non-root user (to whom only non-priviledged ports are available). Coupled with the --filesuffix option, you can also use this feature to run multiple instances of the server on the same host.

-tn, --mtimeout=n

Sets to n seconds the amount of time the server will wait for a needed GSM module instance to become free. Overrides the compiled-in default stored in the "M_TIMEOUT" macro defined in server/sms_serv.h. Acceptable values for the interval range from 0 (zero) to MAXINT. Compiled-in default as shipped: 90 secs (= 1.5 min). Of course, setting this value to 0 means that the server will abort immediately when no module is available.

-Fs, --defaultdomain=s

This option allows you to override the default DNS domain that the sms_serv server will be working for. The default domain is used, among others, in the From: part of bounced-back email messages sent to the administrator when queued SMS messages can't be delivered.
The server software should automatically detect the DNS domain it is working for (that is, provided its hostname properly resolves), but there are situations where you might want to override this (an example of such is when the server is working within an MS ActiveDirectory environment, where the internal DNS domain (the AD domain) is different from the SMTP mail domain (the one published "outside") -- yes, I've seen such a place !).
The server, once started, will report the DNS domain it is working for in its announce (visible when you telnet to the machine the server is running on, on port 6701 [default value, see option -p to alter it]).

-Ms, --smtprelay=s

Sets to s the name of the SMTP relay that will be used by the mail sending routine. By default, the compiled-in SMTP relay is "localhost" -- which means that you should have a properly configured and running sendmail on the SMSLink server (even if all sendmail does is forward to a "smart relay" - the "DS" macro). This option allows you to override this behaviour and to address your mail directly to the appropriate SMTP relay.

-bs, --bounceaddr=s

Sets to s the email address of the administrator that will receive the bounced-back emails each time a queued SMS message can't be delivered after maxqruns attempts. By default, this is "postmaster".

-zs, --charset=s

The character set to be used when encoding / decoding SMS messages to or from PDU format. Use sms_serv -h to list all supported character sets, the token you have to specify instead of s as parameter for this option, and the compiled-in default.

-d[n], --debug[=n]

Sets the debug level. If omitted, debug is turned off, and only the normal logging takes place. If the option is used, but the <level> is omitted, DEBUG_ALL is assumed. The <level> parameter allow you turn on or off special debug elements. This parameter is in fact a set of flags, whose meaning and value are defined in sms_serv.h.

-h, --help

Displays a short help text with the current program version and a list of supported options, then exits.

-v, --version

Displays the program version string and exits.

Command Language

Commands

he | help [command]

When used without parameters, this command displays a list of all available commands. When used with a parameter, it displays a short help text if the parameter is a word of the language.

clear [item]

Clears the requested item (or reverts it back to its default value when there is one). item can be one of:
- user: sender identification (user name) for logging purposes (reset to the empty string).
- smsc: SMS Message Center (reset to device-level default)
- dest: destination GSM Network Address (i.e. phone number -- reset to the empty string)
- mode: SMS sending mode (reset to device-level default).
- message | msg: message text to be sent to destination (reset to the empty string).
- priority | prio: queued message priority (reset to the default message priority).
- debug: server-side debug level (reset to 0).

When used without parameter, this commands clears all items (except debug).

set item = value

Sets the requested item to the specified value. item can be one of:
- user: sender identification (user name) for logging purposes
- smsc: SMS Message Center (see your provider or use default value)
- dest: destination GSM Network Address (i.e. phone number)
- mode: SMS sending mode. Values are given as single letter (not case-sensitive). 'A' or 'T' are understood as text-mode, 'B' or 'P' are understood as PDU-mode.
- message | msg: message text to be sent to destination
- priority | prio: message priority (relevant only when the message is to be queued locally).
- debug: server-side debug level

user, dest and message are required and have no default value. smsc is optional and defaults to whatever value is set by the administrator in the /etc/gsmdevices file.

user and message values have to be quoted. dest and smsc items expect a phone number as value. Phone numbers can be quoted but don't have to be. In addition to numbers, they can contain a "+" (international call symbol) and any of the following separation characters: [/.-]. Those separation characters are purely cosmetics and will be stripped off before being sent to the GSM module for transmission.

message value can be maximum 160 characters long (surrounding quotes not included). Longer messages will be truncated to the first 160 characters, and the user will be warned about it.

Maximum length for user is 12 characters.

priority defines the priority of the message within the server outbox queue. This parameter is meaningfull only when the message actually gets queued. By default, a medium value is used. The user is then able to select, for each message, a priority value higher than average or lower. Priorities are most useful when use in conjunction with the obchklimit command-line option. You can then arrange for user-issued messages to get queued at medium priority, get the batch messages queued at below-average priority, while reserving high priority for alert messages. As shipped, the server uses 3 as default priority, and uses a range going from 1 (highest) to 5 (lowest).

debug is a set of flags specified as an integer value, ranging from 0 to DEBUG_ALL (see sms_serv.h for the value and meaning of those flags). Any change to the value of this parameter will affect the current session between client and server only, and the server side of it only. Neither the parent process, nor any other child will be affected.

send

When all parameters are filled in as required, use this command to send the SMS message. The user will have to wait during the time it takes to send the message, and all commands sent to the module and their responses will be echoed, so the user is immediately aware of any problem and of its nature. An acknowledgment will be returned when done, including the message ID given to this job by the GSM module (cyclic counter, from 0 to 255).

post

This command will first attempt a single regular send (i.e. attempts immediate delivery of the SMS to the SMSC). If it fails (e.g. because no modem device is currently available), the message will be queued for later delivery. For details on how send works, please see above. For details on how queue works, please see below.

queue

When all parameters are filled in as required, use this command to queue the message for later delivery. Inserting the message in the queue should always succeed (unless there is a serious problem with your server, e.g. lack of disk space). When queueing is successfull, the message queue ID is returned. Queued items are then processed by the outbox processing daemon. Queueing of messages is only allowed when the outbox processing is enabled (see option -o above for details on how to enable it). The administrator can choose to have the server queue items as files or as database records (see option -q above).

exit | quit | bye

Closes the connection and leaves the program.

sh | show [item]

Displays the current setting for the specified item, where item is one of:
- user: sender identification (user name) for logging purposes
- smsc: SMS Message Center (see your provider or use default value)
- dest: destination GSM Network Address (i.e. phone number)
- mode: SMS sending mode
- message | msg: message text to be sent to destination (and its length)
- priority | prio: queued message priority
- debug: current server-side debug level

When used without parameter, show displays the current settings for all parameters (except debug).

dl | devicelist [l]

Lists registered GSM devices. Those are configured through the /etc/gsmdevices file. The fields provided in the output are the following:
- L: Lock status of the device ('.' = free, '*' = locked).
- Owner: PID of the process using the device ('0' when free).
- Device: Unix device name
- CallerID: the GSM network address (its phone number)
- Def SCA: default Service Center Address (or SMSC)
- M: default sending mode for the device ('0' = PDU, '1' = text).
- Provider: Network Provider name
An optional l command parameter can be used to get a "long" version of the device list. This long version displays, for each configured device, the entire contents of the struct gsms_def including statistical informations, driver used and features enabled.

stats

Shows per-device server-side statistics and counters. The fields provided in the output are the following:
- device: Unix device name
- Sent OK: number of SMS successfully sent by that device
- Sent FAIL: number of sending failures on that device
- Recvd OK: number of SMS successfully received by that device
- Recvd FAIL: number of reception failures on that device
- Unlock: number of UNLOCK events on that device
The server uptime is then displayed, to allow one to know the amount of time covered by the statistics that were just listed.

qstat

If queueing is enabled, this command will list the current contents of the queue (list of queued items with their respective queue ID). It will also display the selected queueing method, as well as the maximum number of queue runs that each queue item can survive without being successfully delivered (see option -r above). When the selected queueing method is file but the access to the backend database is enabled as well, the command will list the queue contents from both sources. (In that case, both sources will be processed by the outbox processing daemon, but only the file queue will be manageable from within the sms_serv module. The DB queue, in this case, should be managed through some other means (e.g. command-line SQL client)). When the queueing feature is disabled, the qstat command will tell you so.

qdel <id>

This command allows you to remove items from the queue. The mandatory id parameter it the item queue id as reported by the qstat command. When the selected queueing method is file but the access to the backend database is enabled as well, the qdel command will only act on the file-based queue. The database-based queue, in this case, should be managed from outside SMSLink (e.g. through some command-line SQL client).

purge (inbox | outbox) [scope]

This command will remove all sent / processed items from the specified DB table (sent in the case of the outbox table, processed in the case of the inbox [please note that setting the 'processed' field to 'y' in the inbox table is the responsibility of the third-party app. doing the processing]). You can use in as short for inbox, and out as short for outbox. When requesting to purge the outbox, an additional 'scope' parameter can be given (when supplied for the inbox table, it will be silently ignored). Acceptable values are all, sent and fail. The 'scope' parameter determines whether all, only 'sent' or only 'failed' outbox items will be removed ('all' means 'sent' + 'failed', of course). You can shorten the scope by the first letter of its value ('a', 's' or 'f'). When 'scope' is omitted, 'all' is implied.

ut | uptime

Displays the server uptime in days, hours, minutes and seconds.

acl | aclist

Lists all the ACL entries successfully loaded from the configuration file (see gsmaccess (5) ). Since the order of the entries is used to grant or reject access, this order is preserved in the listing. Usefull for debugging configuration issues.

Files

/etc/gsmaccess
Defines IP-based access rules to the service (ACL).

/etc/gsmdbtab
Contains the parameters of the connection to be opened to the back-end MySQL database (server name, database name, username and password).

/etc/gsmcaps
"Driver" file, containing a few fields defining the properties and capabilities of each supported GSM model.

/var/spool/smslink/inbox
File where the incoming messages will be stored. The file format is plain text with Comma Separated Values (CSV) to make it easily parsable by any external application (such as sms2mailgw (1) ). The records are separated by the newline character. The fields are as follows:
- GSM device: The full Unix device name of the GSM module that received the message. In case your server is configured with multiple GSM instances, this allows an external application to discriminate between instances when needed.
- Message ID: The ID assigned by the SIM to the message. Increments sequentially from 0 to 255, then reverts back to 0.
- Sender number: The sender's network address (GSM dialing number).
- Date: The date the message was sent.
- Time: The time the message was sent.
- Message text: The message text. It will always be quoted to protect special characters such as field separators (commas) in the text.

/var/spool/smslink/checkpoint
Empty file "touched" by the server module (in order to alter its timestamp) after a mailbox check. The timestamp info of this file is used by sms2mailgw (1) to synchronize its runs with the server module's checks.

/var/spool/smslink/outbox/
This is actually a directory where all file-based queue items will be stored, one file per queue item.

Bugs

See Also

The INSTALL, TODO and README documents in the sources tree.

Copyright

Part of the code is (c) Riccardo Facchetti.

The code also includes contributions from Philipp Klaus <pklaus@access.ch>, Andrew Worsley <epaanwo@asac.ericsson.se>, Ing. Andrea Vettori <a.vettori@inetronics.com> and numerous others. All contributors are acknowledged in the CHANGELOG document, and in the comment headers of the source files they modified.

SMSLink has been released to the public under the GNU GPL.

Home page: <http://smslink.sourceforge.net/ >

Table of Contents

• Name
• Synopsis
• Description
• Options
• Command Language
• Commands
• Files
• Bugs
• See Also
• Copyright