| Search website: |
|
Advanced Server Software
|
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.
- Delivery Modes
- Troubleshooting
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"
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.
| 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. For ports above COM9 the setting must be formatted \\.\COMxx where xx is the port number, eg \\.\COM40 |
| 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. |
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.
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 |
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
SMSGate currently supports several different SMS delivery modes; delivery via a GSM modem connected to the PC via the COM (serial rs232) port (often a USB connection emulating a COM port), delivery via an online service using HTTP or SMTP as the transport method and the facility to integrate your own method via "robot" mode.
In addition SMSGate has untested SMPP support. If you have an existing SMPP connection and are interested in SMSGate we would be pleased to work with you testing SMSGate for use with your connection. It would give us the opportunity to fix any problems and refine any rough edges present in the SMPP code.
To configure these delivery modes you edit the smsgate.ini file which can be found in the c:\windows or /etc directories (note that there is a backup copy in the smsgate installation directory eg c:\smsgate, do not confuse this with the active copy)
To use a GSM modem you configure the delivery_mode (or send_mode and recv_mode) setting(s) to "gsm" and configure the modem using the various gsm_ settings eg. gsm_com, gsm_baud, gsm_number, etc. There are also a number of compatiblity settings eg cpin_ok for various modem behaviours we have encountered, you should initially ignore these settings and only modify them when consulting the Troubleshooting section below.
To use an online service which expects SMTP requests to send SMS you use "smtp" mode. This mode allows you to send SMS but does not allow the receipt of replies. To configure this mode you set send_mode to "smtp" and recv_mode to "none". It is in fact possible to send using SMTP online SMS services without using SMSGate, you could configure SurgeMail to send to the service directly. One reason you might use SMSGate is that SMSGate will parse the incoming email, strip html tags and format the email as specified by the sms_format (and other settings) this parsing can be very useful.
To use an online service which expects HTTP requests to send SMS you use what we call "robot" mode, this allows you to send SMS but does not allow the receipt of replies. To configure robot mode you set send_mode to "robot" and recv_mode to "none". Next you setup the robot process with robot_cmd, eg. robot_cmd c:\smsgate\sms_robot.exe. This sms_robot.exe binary should come with your SMSGate download. Lastly you configure the robot process itself, you do this by editing the sms_robot.ini configuration file. The configuration file comes with some example settings, modify them to suit what the online service expects.
To integrate your own method you use "robot" mode as described above in the handling of HTTP requests. The difference is that you code/provide your own robot process which delivers the sms message in it's own way. The "robot" protocol is fairly simple, SMSGate will execute the specified process and pass the following enviroment variables:
| SMS_LENGTH | The length of the formatted SMS message in bytes. |
| SMS_FROM | The from email address. |
| SMS_TO | The destination SMS number. |
It will then send the body of the formatted SMS message to the process on it's stdin pipe. It expects a single line response saying either "SUCCESS" indicating the message was delivered or a one line status or error message indicating the reason for the failure. This response is logged in the message record logs.
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.
A good test is to connect to the modem with Hyperterminal and see if you can communicate with it, experiment with different baud settings etc. Some commands to send as a test AT, ATE1, ATS3?, ATS4?. Remember, if you're trying to connect to a port number higher than COM9 you need the alternate gsm_com setting format, eg. gsm_com \\.\COM40
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.
