FOXBOX DOCS Official documentation

1. Gateway and processes launch.
2. Configuration.
3. SMS message queuing.
4. System status information and services.
5. Storefile and dump (in case of “stop and clear the queue”).
6. Additional documentation.

The system is based on two processes:

• Bearerbox;
• SMSBox.

Bearebox takes data from storefile and transfers them to the defined SMSC.
SMSbox accepts / verify the message queuing requests and deposits them into the storefile.

The Bearerbox consists of two separate processes: one is the active and the other is its watchdog; if the active process drops the watchdog takes its place and starts a new spare.

To launch the processes use the script:
/pschk.sh

Although the processes are very stable, it's recommended to start pschk.sh via Crontab every minute to ensure script relaunch after an hypothetical processes fall.

The configuration file is located in:
/etc/kannel.conf
and contains these sections:

• core.
• SMSbox.
• smsc.
• sendsms-user.
• wapbox.

Core
The core section defines the main PATH system:

• log-file = “/var/log/Kannel/bearerbox.log”
• access-log = “/var/log/Kannel/access.log”
• store-file = “/var/log/Kannel/storefile.log”

The Bearerbox.log file, according to the defined verbosity, will show debugging information relative to SMSC communications.
The Access.log file will log all the message queuing requests and DLRs.

Example:

2011-03-19 14:38:48 Sent SMS [SMSC: smppf] [SVC: userf] [ACT:] [BINF: 18042] [FID: 1533151279] [from: entersrl] [to: 393409007144] [flags: - 1:0: -1: -1:3] [msg: 5: test8] [udh: 0:]
2011-03-19 14:38:48 Sent SMS [SMSC: smppf] [SVC: userf] [ACT:] [BINF: 18042] [FID: 3355996176] [from: entersrl] [to: 393409007144] [flags: - 1:0: -1: -1:3] [msg: 5: test8] [udh: 0:]
2011-03-19 14:38:48 Sent SMS [SMSC: smppf] [SVC: userf] [ACT:] [BINF: 18042] [FID: 3223118989] [from: entersrl] [to: 393409007144] [flags: - 1:0: -1: -1:3] [msg: 5: test8] [udh: 0:]

The “Storefile.log” file contains all the outgoing SMSs and incoming DLRs.

SMSBox
The SMSbox is the SMS-send interface and manages the socket HTTP (the socket HTTP port is defined in sendsms-port file).

To obtain the SMS queuing it's necessary to launch a GET HTTP request on the indicated port, passing the mandatory parameters.
Configured port: 13013

SMSC
The SMSC group is used to setup bindings to the SMPP providers servers.
The pre-installed configuration is a 2 SMPP server load-balancing conf. type, but it can be defined by the user.

SENDSMS_USER
Defines the SMSbox login name, password and ACLs.
It's needed to specify the source IP to be able to append SMSs.

• user-deny-ip = “*. *. *. *”
• user-allow-ip = “127.0.0. *; 93.174.68.48, 89.96.38.14”

WAPBOX
Defines the parameters for sending WAP PUSH messages.

To append a text message it's necessary to use an HTTP GET call.
Example:

http://127.0.0.1:13013/cgi-bin/sendsms?username=entersrl1srl&password=S1mA1up&dlr-mask=31&dlr-url=http%3A%2F%2F127.0.0.1%2Fdlr.php%3Foa%3D%25p%26da%3D%25P%26smsc%3D%25i%26dlr-type%3D%25d%26detail%3D%25a%26tempo%3D%25t%26id%3D%25i%26delr%3D%25A%26user%3D%25n%26foreign%3D%25F%26idgen%3D10&binfo=18042&to=393409007144&from=entersrl&text=test1

The parameters are:

• username (defined in the sendsms-user file).
• password (defined in the sendsms-user file).
• dlr-mask (the mask of the DLRs).

Types

• 1: delivery success,
• 2: delivery failure,
• 4: message buffered,
• 8: SMSC submit,
• 16: SMSC reject,

The dlr-mask can be extended by adding “type” values.
Example:

• use mask1 to obtain only the delivered messages DLRs.
• use mask2 to obtain both the delivered and not-delivered messages DLRs.
• use mask31 as the most complete mask (1+2+4+8+16).

• 1: delivered messages.
• 2: not-delivered messages.
• 4: buffered messages (the destination terminal is off or unreachable, system wait for “expire” before giving the outcome).
• 8: return the SMSC ACK (the confirmation that SMSC has accepted the request).
• 16: indicate if the message was rejected (for example when letters, rather than MSISDN, were inserted into destination field).

The dir-url is the URL called when the SMSC return the delivery report, and contain all related informations.

Particular attention should be paid to the last parameter of the URL: idgen.
idgen is the ID necessary to match the DLRs, and must be passed in URLENCODE format (http://www.w3schools.com/TAGS/ref_urlencode.asp).

The pre-installed configuration calls http://127.0.0.1/dlr.php, passing all the available parameters.
dlr.php save data in “append” mode into the file /var/www/html/dlr.txt (.CSV type, “;” separator).

dir.php data are subdivided into columns:

• Type: the DLR type.
• SMSC name: the ID specified into SMSC group configuration ( SMPPF).
• DLR data: all data returned by SMSC (e.g. id:502e21ae sub:001 dlvrd:001 submit date:1300548579 done date:1300548579 stat:DELIVRD err:000).
• user ID: the “name” specified into sendsms-user group ( userf).
• Timestamp: the receipt timestamp.
• MSISDN: the MSISDN destination number.
• sender: the specified message sender.
• IDGEN: the ID specified into SUBMIT.

DLR examples:

8;smppf;ACK/;userf;3662288417;393409007144;entersrl;2
8;smppf;ACK/;userf;119834508;393409007144;entersrl;3
8;smppf;ACK/;userf;230003381;393409007144;entersrl;4
1;smppf;id:24b9502b sub:001 dlvrd:001 submit date:1300548579 done date:1300548579 stat:DELIVRD err:000 text:  ;userf;616124459;393409007144;entersrl;2
1;smppf;id:5dbc5794 sub:001 dlvrd:001 submit date:1300548579 done date:1300548579 stat:DELIVRD err:000 text:  ;userf;1572624276;393409007144;entersrl;4
1;smppf;id:a620001b sub:001 dlvrd:001 submit date:1300548579 done date:1300548579 stat:DELIVRD err:000 text:  ;userf;2787115035;393409007144;entersrl;3

The dlr.php file is located into /var/www/html/dlr.php.

Binfo
The service-type, or billing-info; it's the parameter that mBlox or the SMS vendors apply to your profile.

To
The SMS destination MSISDN; it should be specified with country code without the “leading +” (e.g. 393409007144).

From
The SMS numeric or alphanumeric sender (11 chars); if not specified it will be used the default value specified in the “default-sender = entersrl” configuration.

WARNING: when using numeric sender always place before the “+” char, as a ministerial decision made it mandatory; omitting “+” char can result into not-delivered messages, due to carrier filters.

Text
The text of the SMS in charset UTF-8 format (e.g. for Arabic etc. use the additional parameter & coding = 2).

Into the /home/cantaluppi/ folder there are some examples to try execute calls:

• testsms.php (sends an individual SMS).
• test1000sms.php (execute a loop and sends 1000 SMS to a custom recipient. Useful for benchmark tests).

The speed reached today during tests is 326SMS/sec. on a single channel.

The URL http://127.0.0.1:13000/status provide system status:

Kannel bearerbox version `1.4.3 '.
Build `Mar 19 2011 10:52:21 ',` compiler 4.1.2 20080704 (Red Hat 4.1.2-48)'.
System Linux 2.6.18-194.32.1.el5 release, version # 1 SMP Wed Jan 5 17:52:25 EST 2011 x86_64 machine.
Localhost.localdomain hostname, IP address 127.0.0.1.
Libxml version 2.6.26.
Using native malloc.

Status: running, uptime 0d 2h 45m 10s
WDP: received 0 (0 queued), sent 0 (0 queued)

SMS: received 1541 (0 queued), sent 1034 (0 queued), store size 0
SMS: inbound (0.64,0.38,0.16) msg/sec, outbound (0.42,0.26,0.10) msg/sec

DLR: 527 queued, using internal storage

Box connections:
smsbox:smsbox1, IP 127.0.0.1 (0 queued), (on-line 0d 2h 45m 0s)

SMSC connections:
smppf    SMPP:lab2.kdev.it:2346/2346:entersrl11:KDEvsmP1 (online 9898s, rcvd 1541, sent 1034, failed 0, queued 0 msgs)

The commands available on this interface are:

• status
• store-status
• log-level
• shutdown
• suspend
• isolated
• resume
• restart
• flush-dlr
• stop-smsc
• start-smsc
• reload-lists

In case of Stop and clear the queue .

After launching kill command on Bearerbox to pause a queue (e.g. in the case of incorrect launch of the queue), is necessary to remove both the storefile.log and storefile.log.bak files, otherwise the queue will not be flushed.

The Kill command will also cause that everything that populates the pipeline will be stored into the file storefile.log.bak: restarting demons will result in re-enqueueing data into storefile.log file.

To permanently destroy the queue is necessary to delete both the storefile.log and storefile.log.bak files.

Currently is not possible to perform a selective modification on the queue: the queue can only be entirely deleted but not altered (e.g. by removing messages linked to a particular sender).

• Open SMPP Box User Guide (.PDF)
• http://www.kannel.org/download/1.5.0/userguide-1.5.0/userguide.html