Operation Manual for OutboxSMS-Lite

Operation Manual for OutboxSMS-Lite

Copyright 2006-2016 Felltech Limited. All rights reserved The use and copying of this product is subject to a license agreement. Any other use is prohibited. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system or translated into any language in any form by any means without prior written consent of Felltech Limited. Information in this manual is subject to change without notice and does not represent a commitment on the part of the vendor. 1

Felltech Ltd Milton Hall Ely Road Milton Cambridge CB24 6WZ email: info@felltech.com www: www.felltech.com Edition 1.00 First Published 2012 Last Revised 2016 2

Contents Package Contents... 4 Checklist... 4 Mobile Network SIM Card... 4 Wireless Reception... 4 LAN... 4 IP Address Configuration... 4 Email Server... 4 Power Supply... 4 Hardware Installation... 5 Installing SIM Card... 5 LAN Port... 6 Antenna... 6 Connecting Power... 6 Configuring OutboxSMS... 7 Configuring Modems... 7 Email Server Configuration... 8 Message Routing Tables... 10 Email To SMS Routing... 11 SMS To Email Routing... 15 Logging Options... 18 General Options... 19 GSM Frequency Band Settings... 19 Poll Period... 19 Telephone Number Parsing... 19 SMS Send Error Handling... 20 Send Message... 21 Receive Messages Tab... 21 OutboxSMS-Lite Linux Shell Access... 23 Starting and Stopping the Gateway Service... 23 Changing The IP Address... 23 Changing DNS Servers... 24 Changing Date and Time... 24 Web Server... 24 Viewing OutboxSMS Logs... 24 Web Service Interface... 24 Main File Inventory... 25 Main Executable Files... 25 Daemon/Start Stop Script... 25 Database Files... 25 Configuration File... 25 Web Service Files... 25 Web Server Files... 25 Maintenance... 26 OutboxSMS-Lite Data Folders... 26 Message Folders... 26 3

Package Contents The product package should contain the following items: OutboxSMS-Lite appliance Mains power block This manual Stubby Antenna Checklist Operation Manual for OutboxSMS-Lite Mobile Network SIM Card You must have a SIM card from a local (to you) mobile network provider, with credit (if it s a prepaid SIM card), or with an activated monthly account. Check the SIM card status by installing it in an unlocked mobile phone before fitting into OutboxSMS-Lite. Wireless Reception The OutboxSMS-Lite unit must be sited in a location with good mobile reception from your mobile network provider. Check this with a normal mobile phone before installing OutboxSMS-Lite. If OutboxSMS-Lite is going to be located in an equipment room with poor mobile reception, Felltech Ltd can supply an external wall mounted antenna. Please contact Felltech sales for more information. LAN OutboxSMS-Lite only connects to networks that use the Internet Protocol (IP) as their primary networking protocol. IP Address Configuration OutboxSMS-Lite is shipped pre-configured with a fixed IP Address of 192.168.1.107. So, if the host network has an address configuration incompatible with this, OutboxSMS-Lite will need to be connected off-net, and the address changed before it can be connected to the host network. OutboxSMS-Lite can be configured with a dynamic IP address using a DHCP server, although this is not advisable as it is important to have a fixed IP address to locate the unit on the network. Email Server OutboxSMS-Lite connects to email servers using the POP3 protocol to retrieve email, and the SMTP protocol to send email to the email server. Power Supply A mains power block supporting voltages between 100V and 240V is supplied. This comes with approximately 1 metre of low voltage cable. OutboxSMS-Lite should be sited in easy reach of a power outlet. The power cable should NOT cross walkways, or be left to trail on the floor or provide a trip hazard. OutboxSMS-Lite power block can accept a power supply voltage between 100Vac and 240Vac. The power supply auto-adjusts to the voltage range. 4

Hardware Installation Installing SIM Card A SIM card needs to be fitted to OutboxSMS-Lite, this is fitted via a slot in the front panel. SIM Fitting instructions: 1. Ensure the OutboxSMS-Lite unit is powered off. 2. Hold the SIM with the contact pads facing up, and the notch facing towards the unit, as indicated in the photo below. 3. Push the SIM card into the slot. There should be a click when the card is pushed home. It may be necessary to use a screwdriver or similar device to push the card fully home. When fully home, the edge of the SIM card should be below the surface of the front panel. SIM Removal Instructions:- Push the SIM card in and release. The socket should eject the card a short way to allow it to be fully extracted. It may be necessary to use a screwdriver or similar implement to do the initial push. 5

Connecting OutboxSMS LAN Port Operation Manual for OutboxSMS-Lite The OutboxSMS-Lite appliance supports one type of Ethernet LAN connection: RJ45 shielded twisted pair (STP) cabling. The LAN port can support 10Mbit and 100MBit network speeds and auto-detects which connection speed is applied. Antenna OutboxSMS-Lite is usually supplied with a multiband adjustable knuckle whip antenna. This connects directly to OutboxSMS-Lite via an external SMA Female connector. If the appliance is sited in a poor reception location such as an equipment room, it is necessary to fit an external wall mounted antenna. This connects to OutboxSMS-Lite via the external SMA Female connector, in-place of the whip antenna. Connecting Power Plug the DC power connector end of the power block into the power port on OutboxSMS-Lite and plug the other end into a wall power outlet. There is no power switch on OutboxSMS-Lite, so as soon as power is switched on at the wall, power will be applied to the appliance. The green power LED on the front of the unit should light up, then the yellow modem status LED should flash sporadically, indicating that the modem is active. 6

Configuring OutboxSMS The OutboxSMS software is an Email to SMS gateway system. It converts email messages into SMS text messages, then delivers the messages to mobile phones. It also converts SMS text messages into email messages and forwards them to recipients email inboxes. The software supports a single GSM modem for sending and receiving the SMS messages. The software operates on the Linux/ARM operating system. It is configured and maintained from a Management Console. Configuring Modems Start the OutboxSMS Management Console: Start->Program Files->OutboxSMSLite->SMS Gateway MC. Select the Modem Config tab. 7

Operation Manual for OutboxSMS-Lite Email Server Configuration To configure the email links, click on the Email Server Setup tab. POP3 or IMAP The OutboxSMS server can retrieve mail from either a POP3 mailserver or an IMAP mailserver. Select the preferred mailserver type using the combo box: POP3 Receiving Email Option 1 Server Address Either the URL or IP address of the POP3 server address. Server Port The internet port number to connect to on the POP3 server. Typically this is port 110 Login Name The username used to login to the POP3 server Password The password corresponding to the login name on the POP3 server IMAP Receiving Email Option 2 Server Address Either the URL or IP address of the IMAP server address. Server Port The internet port number to connect to on the IMAP server. Typically this is port 143 Login Name The username used to login to the IMAP server Password The password corresponding to the login name on the IMAP server SMTP Server Address Either the URL or IP address of the SMTP server address. Server Port The internet port number to connect to on the SMTP server. Typically this is port 25 Enable Authentication If ticked, enables authentication information to be sent to the SMTP server Login Name The username used to login to the SMTP server 8

Password The password corresponding to the login name on the SMTP server 9

Message Routing Tables Messages received by OutboxSMS pass through the system and are directed based on the rules held in the routing tables. There are two sets of tables; one set for email to sms and another for sms to email. The routing tables can be accessed via the Message Routing tab. Also on the Message Routing tab page is a setting for the country code. This should be set to the country code of the country the OutboxSMS system is located. This code is used to route messages correctly between different countries. 10

Email To SMS Routing When an email is received by the SMS Gateway, there are a number of routing rules applied to the message to try to determine where the message will be routed. The rules are applied one after the other. The order the rules are applied can be altered by adjusting the entries in the table on the Routing Options tab. However, the Barring rule is always applied first. Routing Options The Routing Options allows you to alter the order in which the routing rules are applied to the message. Route By To Address (Parse) The OutboxSMS gateway software examines the To address of the email to see if there is a telephone number in the address. For instance, the OutboxSMS will extract the telephone number 01434380000 from the following email address:- 01434380000@felltech.com - or - Ian McLauchlan 01434380000@felltech.com 11

Route By To Address (Table) The OutboxSMS gateway software examines the To address of the email, then tries to match the address to an entry in the Route By To Address table. If it matches, the message will be routed to the corresponding telephone number in the table. To add an entry to the table:- 1) Open the OutboxSMS Management Console, and select the Message Routing tab. 2) Click the Edit Email To SMS Tables button. 3) Select the Route By To Address tab. 4) Click the Add New Entry button 5) In the dialog box, enter the email address you wish to match against in the Pattern text box. Enter the destination telephone number in the Destination text box. 6) Click OK Route By Subject (Parse) The OutboxSMS gateway software examines the Subject field of the email to see if a telephone number can be extracted. For instance the following examples are acceptable:- 01434 380000 - or - +44 1434 380000 12

Route By Subject (Table) Operation Manual for OutboxSMS-Lite The OutboxSMS gateway software examines the Subject field of the email, then tries to match the first characters in the field to entries in the Route By Subject table. If it matches, the message will be routed to the corresponding telephone number in the table. To add an entry to the table:- 7) Open the OutboxSMS Management Console, and select the Message Routing tab. 8) Click the Edit Email To SMS Tables button. 9) Select the Route By Subject tab. 10) Click the Add New Entry button 11) In the dialog box, enter the token you wish to match against in the Pattern text box, e.g. sales, or promo1. Enter the destination telephone number in the Destination text box. 12) Click OK 13

Barred From Email The OutboxSMS gateway software tries to match the email From address to an entry in the Barred From Email table. If it matches, the resulting action it takes depends if it is configured as Whitelist or a Blacklist table. If it is configured as a Whitelist: The message will be allowed through. Only addresses in the in the Whitelist are allowed to be routed. If it is configured as a Blacklist: The message will be barred. Only addresses NOT in the Blacklist are allowed to be routed. 14

Operation Manual for OutboxSMS-Lite Action if can t be routed If the message can t be matched to any of the above rules, it is handled according to the settings in this section. This is configured on the Routing Options tab. The options available are:1. Place message in the Error folder 2. Return the message to the sender 3. Forward the message to email address Action if barred If the message is barred by either the Whitelist or Blacklist test, it is handled according to the settings in this section. This is configured on the Routing Options tab. The options available are:1. Place message in the Barred folder 2. Return the message to the sender 3. Forward the message to email address SMS To Email Routing Route By From Tel The OutboxSMS gateway software examines the From telephone number of the inbound SMS message, then tries to match the telephone number to an entry in the Route By From Tel table. If it matches, the message will be routed to the corresponding email address in the table. To add an entry to the table:13) Open the OutboxSMS Management Console, and select the Message Routing tab. 14) Click the Edit SMS To Email Tables button. 15

15) Select the Route By From Tel tab. 16) Click the Add New Entry button Operation Manual for OutboxSMS-Lite 17) In the dialog box, enter the from telephone number you wish to match against in the Pattern text box. Enter the destination email address in the Destination text box. 18) Click OK Route By Token The OutboxSMS gateway software tries to match the first word of the inbound SMS message to an entry in the Route By From Token table. If it matches, the message will be routed to the corresponding email address in the table. To add an entry to the table:- 1) Open the OutboxSMS Management Console, and select the Message Routing tab. 2) Click the Edit SMS To Email Tables button. 3) Select the Route By Token tab. 4) Click the Add New Entry button 5) In the dialog box, enter the token you wish to match against in the Pattern text box. Enter the destination email address in the Destination text box. 6) Click OK Route By Reply Every message sent in the email to SMS direction is registered in the Route By Reply table. The OutboxSMS gateway software tries to match the from telephone number to an entry in 16

Operation Manual for OutboxSMS-Lite the Route By Reply table. If it matches, the message will be routed to the corresponding email address in the table. Old entries are pruned from the Route By Reply table automatically. Route By To Tel The OutboxSMS gateway software examines the To telephone number (the telephone number of the modem) of the inbound SMS message, then tries to match the telephone number to an entry in the Route By From Tel table. If it matches, the message will be routed to the corresponding email address in the table. To add an entry to the table:1) Open the OutboxSMS Management Console, and select the Message Routing tab. 2) Click the Edit SMS To Email Tables button. 3) Select the Route By To Tel tab. 4) Click the Add New Entry button 5) In the dialog box, enter the from telephone number you wish to match against in the Pattern text box. Enter the destination email address in the Destination text box. 6) Click OK 17

Operation Manual for OutboxSMS-Lite Barred The OutboxSMS gateway software tries to match the message from telephone number to an entry in the Barred From Telephone Number table. If it matches, the resulting action it takes depends if it is configured as Whitelist or a Blacklist table. If it is configured as a Whitelist: The message will be allowed through. Only addresses in the in the Whitelist are allowed to be routed. If it is configured as a Blacklist: The message will be barred. Only addresses NOT in the Blacklist are allowed to be routed. Action if can t be routed If the message can t be matched to any of the above rules, it is handled according to the settings in this section. This is configured on the Routing Options tab. The options available are:4. Place message in the Error folder 5. Return the message to the sender 6. Forward the message to email address Action if barred If the message is barred by either the Whitelist or Blacklist test, it is handled according to the settings in this section. This is configured on the Routing Options tab. The options available are:4. Place message in the Barred folder 5. Return the message to the sender 6. Forward the message to email address Logging Options On the Logging Options tab there is a section Log rotation period which is used to set the age when log and call detail records (cdr) are deleted, and a section which controls what information is stored in the log files. 18

General Options GSM Frequency Band Settings GSM services work on 4 standard frequency bands. Normally the GSM modem/s in OutboxSMS work on the 900/1800MHz band, but this can be different for different operators and countries. Ticking the Auto Band Detection box means that the modem, when powered, will automatically search for the first GSM band it can detect. When it finds a band it will then switch and lock-in to that band. This is ok in the majority of cases, but sometimes there are operators working on two or more different bands. The modem may lock to the wrong band for the SIM card. In this case the band needs to be manually set to your operator s band using the Manual band setting combo. Poll Period The OutboxSMS server polls the GSM modem at regular intervals. The poll period is the duration (in minutes) between polls. Telephone Number Parsing Emails sent to OutboxSMS may have a lot of extraneous numbers and information in the fields that it uses to determine the destination telephone numbers. OutboxSMS applies strict criteria to the information in the fields to determine if the information contains a valid telephone number. The Telephone Number Parsing settings control the minimum and maximum acceptable lengths for telephone numbers. 19

SMS Send Error Handling Operation Manual for OutboxSMS-Lite When OutboxSMS attempts to send messages to the operator s network, there maybe errors reported. Some errors are permanent and some are temporary. This section controls how errors are handled. 20

Send Message The Send Message can be used to send a test SMS message directly from OutboxSMS. The message is sent using the API channel. Receive Messages Tab Any SMS messages received by OutboxSMS that are routed to the API channel are displayed in the table on the Receive Messages tab. 21

Status The Status tab displays a the number of messages sent and received by the OutboxSMS server. 22

OutboxSMS-Lite Linux Shell Access The OutboxSMS-Lite appliance runs on the Embedded Linux operating system. It is possible to login using an SSH client program, such as PuTTY on Windows. To login:- 1. Open PuTTY and enter the IP Address of the OutboxSMS-Lite appliance. A console window should open with a login prompt. 2. Enter the username: root and password password 3. If this is the first time login from the PC, PuTTY will prompt whether to accept the server key. Click yes. 4. The shell prompt should appear. From the shell prompt the majority of Linux command line functions are available. Starting and Stopping the Gateway Service The OutboxSMS server software runs as a Linux daemon, it starts automatically when Linux boots on the appliance. The OutboxSMS daemon can be stopped and started using the init.d outboxsms from the command console. To access this:- 1. Connect to the appliance over the LAN using an SSH client. 2. Login, then at the command prompt type /etc/init.d/outboxsms stop The OutboxSMS daemon can be started again by typing /etc/init.d/outboxsms start Changing The IP Address ### WARNING Be very careful changing IP addresses. If it is set to an invalid or incorrect value, you will not be able to contact the box, so it will need the OS to be returned to Felltech to be re-flashed ### At the command line change directory to /etc/network. Open the interfaces file:- # cd /etc/network # vi interfaces The file will look something like this:- #auto eth0 #iface eth0 inet dhcp auto eth0 iface eth0 inet static address 192.168.1.8 netmask 255.255.255.0 gateway 192.168.1.1 Alter the entries to the required values, then save the configuration file and exit the text editor. Now power cycle the OutboxSMS-Lite, remember that the unit will come back up with the new ip address. 23

Changing DNS Servers Operation Manual for OutboxSMS-Lite To set the nameservers, change directory to /etc and edit resolv.conf. # cd /etc # vi resolv.conf The file format should be like this: search your-dns-search-path nameserver dns1-ip-address nameserver dns2-ip-address nameserver dns3-ip-address Now save the configuration file and exit the text editor. To apply changes, you normally need to bring the network interface down and back up. But this would mean losing contact with the box. So, we just reboot the appliance. Changing Date and Time OutboxSMS-Lite has a battery backed realtime clock, so it is necessary to set the system time and enter the command to write the system time to the battery backed real time clock. 1. At the shell type 'date -s "11 JUN 2012 11:15:00" <RTN>' 2. Then type 'hwclock -w' That will set the current date and time and also update the real time clock Web Server Viewing OutboxSMS Logs OutboxSMS-Lite log and cdr files can be accessed remotely via the web interface. The address to enter in the browser is http://<outboxsms-lite ip address>/log Web Service Interface The OutboxSMS-Lite presents a web service interface via the Web Server. This allows for messages to be sent and received by external applications. The webservices definition file is located at: http://<outboxsms-lite ip address>/messaging.wsdl Example applications written in PHP are available on OutboxSMS-Lite. The files can be accessed from a standard web browser, and can also be examined using the SSH shell. Example message send application: Web browser: http://<outboxsms-lite ip address>/oblc_test_send.php File location: /var/www/oblc_test_send.php Example message receive application: Web browser: http://<outboxsms-lite ip address>/oblc_test_recv.php File location: /var/www/oblc_test_recv.php 24

Main File Inventory Operation Manual for OutboxSMS-Lite Main Executable Files /usr/sbin/outboxsms Daemon/Start Stop Script /etc/init.d/outboxsms Main OutboxSMS server daemon executable The shell script to automate starting and stopping the daemon. Database Files /var/outboxsms/barredemailtosms.db Contains all the barred email addresses for the email to SMS direction. /var/outboxsms/barredsmstoemail.db Contains all the barred telephone numbers for the SMS to email direction. /var/outboxsms/emailsubject.db Contains all the subject field matches for the email to SMS direction. /var/outboxsms/emailtosmsorder.db Contains the order that rules are applied for messages in the email to SMS direction. /var/outboxsms/fromtel.db Contains the from telephone number matches for messages in the SMS to email direction. /var/outboxsms/smsreply.db Holds all the email address / telephone number pairs of all messages sent in the email to SMS direction. These are used to route SMS replies. /var/outboxsms/smstoemailorder.db Contains the order that rules are applied for the messages in the SMS to email direction. /var/outboxsms/smstoken.db Contains the tokens for matching to the first word of an inbound SMS message. For messages in the SMS to email direction. /var/outboxsms/toemailaddress.db Contains the to field address matches for messages in the email to SMS direction. /var/outboxsms/totel.db Contains the to telephone number matches for messages in the SMS to Email direction. Configuration File /var/outboxsms/sms_svr.cfg The main OutboxSMS configuration file. Web Service Files /var/www/messaging.wsdl /var/www/messaging.php /var/www/msgpersistence.php /var/www/oblc_test_send.php /var/www/oblc_test_recv.php The web services definition file The web service interface file Web service function file Example webservice message send Example webservice message receive Web Server Files /var/www/index.html OutboxSMS-Lite web information page 25

Maintenance OutboxSMS-Lite Data Folders The OutboxSMS application data folders are stored under: /var/outboxsms Message Folders /var/outboxsms/pop3error /var/outboxsms/pop3inbox /var/outboxsms/imapinbox /var/outboxsms/imaperror If an error occurs when an email message is retrieved by the POP3 service. The message that caused the error is placed in this folder. Incoming email message files are placed in this folder by the POP3 poll part of the OutboxSMS software. Incoming email message files are placed in this folder by the IMAP poll part of the OutboxSMS software. If an error occurs when an email message is retrieved by the IMAP service. The message that caused the error is placed in this folder. /var/outboxsms/smstexterror If an error occurs with the message when sending the SMS, the message file is placed in this folder. /var/outboxsms/smstextinbox Incoming SMS message files from the mobile network are placed in this folder by SMS receiver part of the OutboxSMS software. /var/outboxsms/smstextoutboxsms messages to go out are placed in this folder. The SMS send part of the OutboxSMS software picks up the message from this folder sends the message, then places it in the SMSTextSent folder. /var/outboxsms/smstextsent /var/outboxsms/smtperror /var/outboxsms/smtpoutbox /var/outboxsms/smtpsent /var/outboxsms/apitextinbox Sent SMS message files are placed in this folder by the OutboxSMS software. If an error occurs when an email message is sent using the SMTP service. The message that caused the error is placed in this folder. Email messages that are to be sent using the SMTP method are placed in this folder. Email messages that have been successfully sent by the SMTP method are placed in this folder. Messages received by the API interface are placed in this folder prior to being routed by OutboxSMS. /var/outboxsms/apitextoutbox SMS messages received by OutboxSMS that are routed to the API channel are placed in this folder prior to being retrieved by the API interface. /var/outboxsms/apitextsent Messages retrieved by the API are placed in this folder. 26

Log File Operation Manual for OutboxSMS-Lite The log file contains a trace of all the activity in the OutboxSMS-Lite gateway software. The log files are located at: /var/log/outboxsms. The log files are formatted plain text files and can be identified by the.log file extension. CDR Format Call Detail Record (CDR) files are located in the log folder at: /var/log/outboxsms. The CDR files are formatted plain text files and can be identified by the.cdr file extension. There is a one line entry in the CDR log per message leg transaction. The message delimiter is the (pipe) symbol. Date/Time Direction/Leg From Address To Address Format yyyy-mm-dd hh:mm:ss This indicates what direction the message is passing through the OutboxSMS gateway. Outbound SMS SMTP Outbound Email Inbound SMS POP3 Inbound Email Full RFC822 specification email address or telephone number. Full RFC822 specification email address or telephone number. Email To SMS Example When the email message arrives at the OutboxSMS gateway an entry is put in the CDR log as follows:- 2006-02-26 11:56:02 POP3 Inbound Email Ian McLauchlan <ianmac@felltech.com> <sms.gateway@felltech.com> This indicates a message from an email address to the email address of the OutboxSMS gateway. The message is then routed out to a mobile phone number. When this happens successfully, another entry is put in the CDR log as follows:- 2006-02-26 11:56:03 Outbound SMS Ian McLauchlan <ianmac@felltech.com> +447900494550 There is a difference in the outbound routed message entry, the from address is marked as the original sender s email address, but the to address is the final destination mobile telephone number. SMS To Email Example When the SMS message arrives at the OutboxSMS gateway an entry is put in the CDR log as follows:- 2006-02-26 11:56:02 Inbound SMS +447900494550 +44123456789 This indicates a message from the sender s mobile telephone number to the telephone number of the OutboxSMS gateway. The message is then routed out to a recipient s email address. When this happens successfully, another entry is put in the CDR log as follows:- 2006-02-26 11:56:03 SMTP Outbound Email +447900494550 Ian McLauchlan <ianmac@felltech.com> 27

There is a difference in the outbound routed message entry, the from address is marked as the original sender s mobile telephone number, but the to address is the final destination email address. 28