|
|
|
SMSGate:
SMS to Email gateway
It allows you to provide
SMS message facilities via email using a gsm modem. It has settable limits
for email address, SMS number and IP's, plus complete logs of traffic
for billing purposes.
It can be integrated
into any mail server allowing sms notification of email, or simply the
ability to send sms via thier existing email client. It can also be integrated
into our DBabble instant message server to allow instant sms messages
to be sent.
The
following sections describe...
- NT
Installation.
- Unix
Installation.
- Important
Settings
- General
usage.
- Commands
- Configuration
settings.
- Troubleshooting
NT
Installation
Download the self
extracting archive from here,
run it and follow the on screen instructions. Or if you would like to
perform an install manuall you can follow the steps below.
- Extract the self-extracting
archive to install directory.
- Run smsgate -install
- Copy smsgate.ini
to the windows directory, i.e. c:\windows or c:\winnt and edit the settings.
see here
- Type "net
start smsgate"
Unix
Installation
Download the self
extracting archive from here,
run it and follow the on screen instructions. Or if you would like to
perform an install manuall you can follow the steps below.
- Extract the tarball
into install directory.
- Run ./smsgate -install.
- Copy smsgate.ini
to the /etc directory, and edit the settings. see here.
- Add SMSGate to
your startup scripts.
Important
Settings
Setting |
Default |
Description |
smtp_inport |
1025 |
Port to listen
on and accept incomming SMTP messages |
smtp_outserver |
<hostname> |
Ip address/name
of the normal SMTP server for outgoing email messages. |
smtp_outport |
25 |
Port the normal
SMTP server is listening on. |
smtp_prefix |
|
Prefix to strip
from incoming email addresses, and to add onto outgoing email addresses,
to turn them into/from phone numbers. |
smtp_domain |
<hostname> |
Domain name to
add to outgoing phone numbers to make them a correct email address. |
delivery_mode |
gsm |
Method of SMS
delivery, currently only 'GSM' is supported, plans to add SMPP, SMTP,
and XML - Let us know if you require a different transport method
from those currently supported. |
phone_country |
|
Country code
for local phones, i.e. 64 is New Zealand |
phone_service |
|
Area / Service
code for local phones i.e. 025 for Telecom, 021 for Vodaphone (New
Zealand values shown) |
gsm_com |
COM1 |
Com port the
GSM modem is connected to. |
gsm_baud |
9600 |
Baud rate to
use talking to modem. |
gsm_number |
|
GSM modem phone
number. |
workpath |
/smsgate |
Path to store
work files, traffic logs etc. |
logpath |
<workpath> |
Path to store
debug log files. |
loglevel |
info |
Level of debugging..
none, error, info, and debug are valid. |
accept_ip |
* |
Wildcard list
of IP address to accept smtp messages from. |
from_limit |
|
Maximum number
of messages from a particular email address in a single day. |
to_limit |
|
Maximum number
of messages to a particular phone number in a single day. |
ip_limit |
|
Maximum number
of messages from a particular IPin a single day. |
General
Usage
SMSGate
is a server, it accepts SMTP style connections on a specified port and
delivers those messages via SMS messages to the given SMS phone number.
It also recieves SMS messages and delivers them via email to either:
- The
address specified in the SMS message.
- The
email address that sent an SMS thru SMSGate to that phone number (if
there is more than 1 it bounces an SMS asking for confirmation of the
email address desired).
It is expected that
you will run SMSGate in conjunction with a normal SMTP server and gateway
specific messages thru to it, allowing SMS notification of email and other
useful features.
A normal SMTP server
is NOT required for incoming SMTP messages but IS required for outgoing
email messages.
SMSGate can run in
conjunction with DBabble allowing you to give sms sending capabilities
to your DBabble instant message users.
Configuration
settings
A default enclosed
in <> means the setting defaults to the setting name in the <>.
<hostname> is a special case, the hostname is the computers host
name and it is looked up upon execution. A setting with 'multi' in it's
description can have multiple values.
Setting |
Default |
Description |
accept_from |
* |
multi;
Wildcard list of email addresses to accept smtp messages from. |
accept_ip |
* |
multi;
Wildcard list of IP address to accept smtp messages from. |
accept_to |
* |
multi;
Wildcard list of phone numbers to send sms to. |
alias_file |
|
see
below |
cbst_one |
false |
Deprecated;
This is now configured automatically. |
cnmi_flush |
false |
Controls
how incoming message indications are flushed, do not change unless
troubleshooting. |
com_debug_file |
|
The
file in which to log data to/from the GSM modem. |
cpin_ok |
false |
Tells
SMSGate to expect an extra OK message from the CPIN command. |
delivery_file |
|
see
below |
delivery_mode |
gsm |
Method
of SMS delivery, currently only 'GSM' is supported, plans to add SMPP,
SMTP, and XML - Let us know if you require a different transport method
from those currently supported. |
email_subject |
$(BODY20) |
Specifies
the format of the subject in the email generated from an incoming
SMS. May contain $(xy) where x can be from, body, or any smsgate.ini
configuration setting and y is the length to truncate that value to.
eg. $(from5) $(body10) |
from_limit |
500 |
Maximum
number of messages from a particular email address in a single day. |
from_limit_msg |
<limit_msg> |
The
message given when the from_limit is reached. |
gsm_baud |
9600 |
Baud
rate to use talking to modem. |
gsm_com |
COM1 |
Com
port the GSM modem is connected to. |
gsm_crlf |
true |
Deprecated;
This is now configured automatically. |
gsm_init |
AT |
The
initialisation string sent to the GSM modem. |
gsm_min_signal |
0 |
If
set > 0 SMSGate waits till the modem signal strength is at least
this value. Possible values include 0 thru 31, 31 being the best possible
signal strength. |
gsm_noinit |
false |
Disables
the gsm_init string. |
gsm_number |
|
GSM
modem phone number. |
gsm_pin |
|
The
PIN number required to access the GSM modem. |
gsm_pin2 |
|
The
PIN2 number required to access the GSM modem. |
gsm_puk |
|
The
PUK required to re-set the PIN number. |
gsm_puk2 |
|
The
PUK2 required to re-set the PIN2 number. |
gsm_signal_timeout |
60 |
How
long to wait (secs) for gsm_min_signal level to be reached. |
home |
\\smsgate |
The
directory to read and write smsgate files from/to. |
host |
<hostname> |
Automatically
configured to the hostname of the computer. |
ip_limit |
0 |
Maximum
number of messages from a particular IP in a single day. |
ip_limit_msg |
<limit_msg> |
The
message to give when ip_limit is reached. |
limit |
|
multi;
see below |
limit_msg |
Limit
reached |
The
default message to give when a limit is reached. |
log_delimiter |
| |
This
is the character to use to delimit fields in the logs, setting it
to "TAB" causes the tab character to be used. |
loglevel |
debug |
Level
of debugging.. none, error, info, and debug are valid. |
logpath |
<workpath> |
Path
to store debug log files. |
phone_country |
|
Country
code for local phones, i.e. 64 is New Zealand |
phone_range |
|
The
range of phone numbers assigned to your SMPP connection, only used
by delivery_mode smpp. (which is completed, tested, but has not been
used in a real live enviroment). |
phone_service |
|
Area
/ Service code for local phones i.e. 025 for Telecom, 021 for Vodaphone
(New Zealand values shown) |
recv_mode |
<delivery_mode> |
Specifies
the mode to use to receive SMS messages. Set this if it's different
to delivery_mode. |
reply_with |
true |
Causes
the text "Reply w/ EMAIL" to be prepended to outgoing sms
messages. |
report |
|
multi;
see below |
robot_cmd |
|
If
using deliver_mode robot then this specifies the robot, this command
is executed and the sms to deliver is sent to it on stdin. Other information
is passed in enviroment variables: SMS_LENGTH, SMS_FROM, and SMS_TO. |
send_mode |
<delivery_mode> |
Specifies
the mode to use to send SMS messages. Set this if it's different to
delivery_mode. |
smpp_addr_range |
* |
This
is sent to the SMPP server as part of the initial connection, it specifies
the addresses you are interested in. |
smpp_host |
|
The
hostname or ip of the SMPP server to use. |
smpp_pass |
|
The
password for access to the SMPP server. |
smpp_port |
2775 |
The
port the SMPP server is listening for connections on. |
smpp_user |
|
The
username for access to the SMPP server. |
sms_best_guess |
false |
When
determining the email to send an incoming SMS to SMSGate will check
in the message text for a destination. Failing that it will send to
the email it has recorded as sending an sms to the incoming number,
provided there is only 1 of them, if there are more than 1 it fails,
unless you use this setting, it will cause it to send to the most
recent. |
sms_bounces |
true |
When
SMSGate cannot determine which email to send the incoming sms to,
it generates a bounce or error sms message and sends it back to the
sms sender, this disables those bounces. |
sms_dcs |
7bit |
This
is the Data Coding Sceme to use in SMS messages, options are 7bit,
8bit, and 16bit. Only applicable in "sms_mode pdu". The
larger the bit count the less characters will fit in the message,
but the greater the range of characters you will be able to use. |
sms_extended |
false |
This
setting enables the extended 7bit DCS mode. |
sms_format |
|
This
specifies the format of the sms when converting email to sms. It can
contain special inserts like $(bodyX) $(nl) or ($headerX) where header
can be any email header. The X specifies the length to truncate the
value at eg. $(body10) shows 10 characters from the body of the email.
eg. sms_format $(subject20)$(nl)$(body) |
sms_ignore |
|
multi;
Tells smsgate to ignore incoming sms messages from this phone number. |
sms_mode |
text |
SMS
messages can be sent in either 'text' or 'pdu' mode, 'text' is human
readable, 'pdu' is encoded data. |
sms_retries |
3 |
Number
of times to retry sending an SMS message. |
sms_smart |
|
This
is an extensible setting for specifying formatting options within
sms message, the only option available currently is "spaces"
which causes smsgate to strip spaces from text and capitalise the
first letter of each word, this is intended to squeeze more text into
the SMS message. |
sms_static |
false |
This
causes smsgate to deliver all incoming SMS messages to the same email
address, that address is made up of the smtp_prefix, gsm_number and
smtp_domain settings eg. <prefix><number>@<domain> |
sms_subject |
true |
This
cause SMSGate to include the email subject in the SMS message body,
followed by an '-' eg. SUBJECT - BODY |
sms_to |
|
multi;
see below |
smtp_debug_file |
|
This
specifies a file to log all SMTP data to. |
smtp_domain |
<host> |
Domain
name to add to outgoing phone numbers to make them a correct email
address. |
smtp_greeting |
SMSGate |
The
initial SMTP greeting string. |
smtp_inport |
1025 |
The
port on which SMSGate listens for incoming SMTP connections. |
smtp_outport |
25 |
Port
the normal SMTP server is listening on. |
smtp_outserver |
<host> |
Ip
address/name of the normal SMTP server for outgoing email messages. |
smtp_prefix |
|
Prefix
to strip from incoming email addresses, and to add onto outgoing email
addresses, to turn them into/from phone numbers. |
smtp_retries |
3 |
Number
of times to retry sending an email via the smtp_outserver. |
smtp_retry_wait |
5 |
Time
(mins) to wait between smtp_retries attempts. |
ssl_cert |
sg_cert.pem |
File
containing the SSL certificate |
ssl_dir |
<workpath> |
Directory
containing ssl_cert and ssl_priv |
ssl_priv |
sg_priv.pem |
File
containing the SSL private key |
to_limit |
500 |
Maximum
number of messages to a particular phone number in a single day. |
to_limit_msg |
<limit_msg> |
Message
to give if to_limit is reached. |
web_allow |
127.0.0.1 |
Port
to allow incoming web admin requests on. |
web_https |
true |
Web
admin is an HTTPS port. |
web_port |
8775 |
Port
to accept web admin connections on. |
webpath |
./web |
Path
to web admin files. |
workpath |
<home> |
Path
to store work files, traffic logs etc. |
The more complicated
settings have several parts to them and require more of an explaination.
The format is shown below on several lines for clarity, in the configuration
file each setting should be on one line.
Setting |
Format |
Description |
alias_file |
file=VALUE
delimiter=VALUE
order=VALUE
required=VALUE |
This
file is used to translate the phone number of an incoming sms into
an email address which is then set as the From address in the email.
The delimiter and order fields specify the format of the file (see
below). Required specifies that a translation is required, if
none is found the message is not sent. |
delivery_file |
file=VALUE
delimiter=VALUE
order=VALUE
|
This
file is used to route an incoming sms based on the the phone number
it comes from to a destination email address. The delimiter and order
fields specify the format of the file (see
below). |
limit |
name=VALUE
ip=VALUE
to=VALUE
from=VALUE
period=VALUE |
Specifies
a rule limiting the SMS messages that can be sent in the specified
time period. Similar to ip_limit, to_limit and from_limit except that
it allows configuration of the time period and name of the rule. ip_limit,
to_limit and from_limit are identical to a limit setting like: limit
name="msgrec" ip="x" to="y" from="z"
period="24" which is a rule called msgrec which allows x
sms from any given ip, y sms to any given number, and z sms from and
given email address in a 24 hour period. The period field is in hours,
unless a unit is specified (d)ay, (w)eek, (y)ear eg. period="2w"
means 2 weeks. |
report |
time=VALUE
to=VALUE
message=VALUE
days=VALUE |
Causes
SMSGate to send a periodic SMS message to proove it is operational.
Time is specified as hour:min eg. 21:45. To is a phone number to send
the report to. Message is the text to include in the report. Days
is a comma seperated list of days of the week and/or a range eg. Sun,Tue-Thu,Sat |
sms_to |
keyword=VALUE
phone=VALUE
prefix=VALUE
domain=VALUE |
SMSGate
looks in the body of all incoming SMS messages for the specified keyword,
the sms must be from a number matching the specified 'phone' wildcard.
The sms is then sent to the email address constructed from prefix,
domain and the word following the keyword. eg: sms_to keyword="dbabble"
phone="*" prefix="dbabble_" domain="domain.com"
will send an email to 'dbabble_regan@domain.com' if an incoming sms
contains "dbabble regan". |
The
delimiter and order fields of alias_file and delivery_file specify the
format of the file. Delimiter may be set to any character or sequence
of characters. One special case "TAB" is supplied to set delimiter
to the tab character. The order field is a comma seperated list with two
possible values PHONE and EMAIL eg. order="PHONE,EMAIL".
For example a setting:
alias_file file="aliases.txt" delimiter="|" order="PHONE,EMAIL"
required="TRUE" would expect the aliases.txt file to look a
bit like this:
+64213334444|regan@netwin.co.nz
+64256667777|regan@netwinsite.com
Troubleshooting
If SMSGate will not
start, it can be one of several reasons:
- A port cannot be
bound, as something else is already using it.
- The GSM Modem could
not be contacted on the gsm_com port.
- The GSM Modem did
not respond as expected.
To identify what problem
SMSGate is having you should have a look in the smsgate.log file, which
can be found in the smsgate installation directory (c:\smsgate or /usr/local/smsgate).
It will contain the error, look for a line containing "Error:",
this will give a clue as to why it will not start.
If the Error line
says:
- "Failed to
load configuration file..." then smsgate.ini has not been created
or is in-accessable (see install.txt)
- "License key
faulty..." then there is a problem with the license key, the rest
of the error should tell you what.
- "Failed to
read (..." then it is having trouble reading the specified file,
does it have permission?
- "Failed to
load message rec..." then it is having trouble reading the msgrec.ip,msgrec.from,msgrec.to
files.
- "Config setting
'gsm_number' required" then you need to specify gsm_number in smsgate.ini
- "Robot_cmd
is required for this delivery_mode..." then you need to specify
robot_cmd in smsgate.ini
- "Failed to
init command channel..." then the port specified by the web_port
setting in smsgate.ini is being used, change this setting to another
port.
- "Failed to
init smtp..." then the port specified by the smtp_inport setting
in smsgate.ini is being used, change this setting to another port.
- "Failed to
init gsm..." there is a problem connecting to or initializing the
modem, set the com_debug_file setting to a path and filename where it
can write some debugging information, then try to start it again, now
open that debug file and have a look at the last command it carried
out, if it was:
- "AT"
then add the setting "gsm_noinit true" to smsgate.ini
and try again.
- "AT+CBST..."
then add the setting "cbst_one true" to smsgate.ini and
try again.
- "AT+CMGF..."
then add the setting "sms_mode pdu" to smsgate.ini and
try again.
If it starts ok, but
behaves strangely then look in the com_raw.log, and find the AT+CPIN command,
if the modem has responded with two lines "+CPIN:.." and then
"OK" you need to add the "cpin_ok true" setting to
smsgate.ini and try it again.
If the problem is
not described above then please send all the log files created by smsgate
to smsgate-support@netwinsite.com with
a description of the behaviour and we will help you solve it.
|