Interception

Starting from 0.7.0, Jasmin provides a convenient way for users to hook third party logics on intercepted messages (submit_sm or deliver_sm) before proceding to The message router.

Interception of message is based on filter matching, just like the router; every intercepted message will be handed to a user-script written in Python.

This feature permits users to implement custom behaviors on top of Jasmin router, here’s some possible scenarios:

  • Billing & charging of MO messages,
  • Implement HLR lookup for a better SMS MT routing,
  • Change a pdu content: fix npi/ton, prefixing/suffixing numbers, etc ...
  • Modify Jasmin’s response for the message: send back a ESME_RINVDSTADR instead of ESME_ROK for example.
  • etc ..

Enabling interceptor

Jasmin’s interceptor is a system service that run separately from Jasmin, it can be hosted on remote server as well; interceptord is a system service just like jasmind, so simply start it by typing:

sudo systemctl start jasmin-interceptord

Note

After starting the interceptord service, you may check /var/log/jasmin/interceptor.log to ensure everything is okay.

Then you need to enable communication between jasmind and interceptord services by editing jasmind start script (locate the jasmind.service file in /etc/systemd) and replacing the following line:

ExecStart=/usr/bin/jasmind.py --username jcliadmin --password jclipwd

by:

ExecStart=/usr/bin/jasmind.py --username jcliadmin --password jclipwd --enable-interceptor-client

The last step is to restart jasmind and check /var/log/jasmin/interceptor.log to ensure connection has been successfully established by finding the following line:

INFO     XXXX Authenticated Avatar: iadmin

Intercepting a message

As stated earlier, interceptor is behaving similarly to The message router, here’s an example of setting up a MO message (deliver_sm) interception rule through jcli management console:

jcli : mointerceptor -a
Adding a new MO Interceptor: (ok: save, ko: exit)
> type DefaultInterceptor
<class 'jasmin.routing.Interceptors.DefaultInterceptor'> arguments:
script
> script python2(/opt/jasmin-scripts/interception/mo-interceptor.py)
> ok
Successfully added MOInterceptor [DefaultInterceptor] with order:0

Same thing apply to setting up a MT message (submit_sm) interception rule, here’s another example using a filtered rule instead of a default one:

jcli : mtinterceptor -a
Adding a new MT Interceptor: (ok: save, ko: exit)
> type StaticMTInterceptor
<class 'jasmin.routing.Interceptors.DefaultInterceptor'> arguments:
filters, script
> script python2(/opt/jasmin-scripts/interception/mt-interceptor.py)
> filters U-foo;DA-33
> order 100
> ok
Successfully added MTInterceptor [StaticMTInterceptor] with order:100

As show in the above examples, the interception rules are straightforward, any matched message will be handed to the script you set through the script python2(<path_to_pyfile>) instruction.

When your python script is called it will get the following global variables set:

  • routable: one of the jasmin.routing.Routables.Routable inheriters (Routable for more details)
  • smpp_status: (default to 0) it is the smpp response that Jasmin must return for the message, more details in Controlling response
  • http_status: (default to 0) it is the http response that Jasmin must return for the message, more details in Controlling response

The script can:

  • Override routable parameters like setting destination or source addresses, short message, etc ...
  • Tag the routable to help the router matching a desired rule (useful for HRL lookup routing)
  • Control Jasmin response by setting smpp_status and/or http_status.

Some practical examples are given below.

Controlling response

The interceptor script can reject message before it goes to the router, this can be useful for implementing third party controls like:

  • Billing and charging authorization: reject message if user has no credits,
  • Reject some illegal message content,
  • Enable anti-spam to protect destination users from getting flooded,
  • etc ...

In order to reject a message, depending on the source of message (httpapi ? smpp server ? smpp client ?) the script must set smpp_status and/or http_status accordingly to the error to be returned back, here’s an error mapping table for smpp:

smpp_status Error mapping
Value SMPP Status Description
0 ESME_ROK No error
1 ESME_RINVMSGLEN Message Length is invalid
2 ESME_RINVCMDLEN Command Length is invalid
3 ESME_RINVCMDID Invalid Command ID
4 ESME_RINVBNDSTS Invalid BIND Status for given command
5 ESME_RALYBND ESME Already in Bound State
6 ESME_RINVPRTFLG Invalid Priority Flag
7 ESME_RINVREGDLVFLG Invalid Registered Delivery Flag
8 ESME_RSYSERR System Error
265 ESME_RINVBCASTAREAFMT Broadcast Area Format is invalid
10 ESME_RINVSRCADR Invalid Source Address
11 ESME_RINVDSTADR Invalid Dest Addr
12 ESME_RINVMSGID Message ID is invalid
13 ESME_RBINDFAIL Bind Failed
14 ESME_RINVPASWD Invalid Password
15 ESME_RINVSYSID Invalid System ID
272 ESME_RINVBCAST_REP Number of Repeated Broadcasts is invalid
17 ESME_RCANCELFAIL Cancel SM Failed
274 ESME_RINVBCASTCHANIND Broadcast Channel Indicator is invalid
19 ESME_RREPLACEFAIL Replace SM Failed
20 ESME_RMSGQFUL Message Queue Full
21 ESME_RINVSERTYP Invalid Service Type
196 ESME_RINVOPTPARAMVAL Invalid Optional Parameter Value
260 ESME_RINVDCS Invalid Data Coding Scheme
261 ESME_RINVSRCADDRSUBUNIT Source Address Sub unit is Invalid
262 ESME_RINVDSTADDRSUBUNIT Destination Address Sub unit is Invalid
263 ESME_RINVBCASTFREQINT Broadcast Frequency Interval is invalid
257 ESME_RPROHIBITED ESME Prohibited from using specified operation
273 ESME_RINVBCASTSRVGRP Broadcast Service Group is invalid
264 ESME_RINVBCASTALIAS_NAME Broadcast Alias Name is invalid
270 ESME_RBCASTQUERYFAIL query_broadcast_sm operation failed
51 ESME_RINVNUMDESTS Invalid number of destinations
52 ESME_RINVDLNAME Invalid Distribution List Name
267 ESME_RINVBCASTCNTTYPE Broadcast Content Type is invalid
266 ESME_RINVNUMBCAST_AREAS Number of Broadcast Areas is invalid
192 ESME_RINVOPTPARSTREAM Error in the optional part of the PDU Body
64 ESME_RINVDESTFLAG Destination flag is invalid (submit_multi)
193 ESME_ROPTPARNOTALLWD Optional Parameter not allowed
66 ESME_RINVSUBREP Invalid submit with replace request (i.e. submit_sm with replace_if_present_flag set)
67 ESME_RINVESMCLASS Invalid esm_class field data
68 ESME_RCNTSUBDL Cannot Submit to Distribution List
69 ESME_RSUBMITFAIL submit_sm or submit_multi failed
256 ESME_RSERTYPUNAUTH ESME Not authorised to use specified service_type
72 ESME_RINVSRCTON Invalid Source address TON
73 ESME_RINVSRCNPI Invalid Source address NPI
258 ESME_RSERTYPUNAVAIL Specified service_type is unavailable
269 ESME_RBCASTFAIL broadcast_sm operation failed
80 ESME_RINVDSTTON Invalid Destination address TON
81 ESME_RINVDSTNPI Invalid Destination address NPI
83 ESME_RINVSYSTYP Invalid system_type field
84 ESME_RINVREPFLAG Invalid replace_if_present flag
85 ESME_RINVNUMMSGS Invalid number of messages
88 ESME_RTHROTTLED Throttling error (ESME has exceeded allowed message limits
271 ESME_RBCASTCANCELFAIL cancel_broadcast_sm operation failed
97 ESME_RINVSCHED Invalid Scheduled Delivery Time
98 ESME_RINVEXPIRY Invalid message validity period (Expiry time)
99 ESME_RINVDFTMSGID Predefined Message Invalid or Not Found
100 ESME_RX_T_APPN ESME Receiver Temporary App Error Code
101 ESME_RX_P_APPN ESME Receiver Permanent App Error Code
102 ESME_RX_R_APPN ESME Receiver Reject Message Error Code
103 ESME_RQUERYFAIL query_sm request failed
259 ESME_RSERTYPDENIED Specified service_type is denied
194 ESME_RINVPARLEN Invalid Parameter Length
268 ESME_RINVBCASTMSGCLASS Broadcast Message Class is invalid
255 ESME_RUNKNOWNERR Unknown Error
254 ESME_RDELIVERYFAILURE Delivery Failure (used for data_sm_resp)
195 ESME_RMISSINGOPTPARAM Expected Optional Parameter missing

As for http errors, the value you set in http_status will be the http error code to return.

Note

When setting http_status to some value different from 0, the smpp_status value will be automatically set to 255 (ESME_RUNKNOWNERR).

Note

When setting smpp_status to some value different from 0, the http_status value will be automatically set to 520 (Unknown error).

Checkout the MO Charging example to see how’s rejection is done.

Scripting examples

You’ll find below some helping examples of scripts used to intercept MO and/or MT messages.

HLR Lookup routing

The following script will help the router decide where to send the MT message, let’s say we have some HLR lookup webservice to call in order to know to which network the destination number belong, and then tag the routable for later filtering in router:

"This script will call HLR lookup api to get the MCC/MNC of the destination number"

import requests, json

hlr_lookup_url = "https://api.some-provider.com/hlr/lookup"
data = json.dumps({'number': routable.pdu.params['destination_addr']})
r = requests.post(hlr_lookup_url, data, auth=('user', '*****'))

if r.json['mnc'] == '214':
    # Spain
    if r.json['mcc'] == '01':
        # Vodaphone
        routable.addTag(21401)
    elif r.json['mcc'] == '03':
        # Orange
        routable.addTag(21403)
    elif r.json['mcc'] == '25':
        # Lyca mobile
        routable.addTag(21425)

The script is tagging the routable if destination is Vodaphone, Orange or Lyca mobile; that’s because we need to route message to different connector based on destination network, let’s say:

  • Vodaphone needs to be routed through connectorA
  • Orange needs to be routed through connectorB
  • Lyca mobile needs to be routed through connectorC
  • All the rest needs to be routed through connectorD

Here’s the routing table to execute the above example:

jcli : mtrouter -l
#Order Type            Rate    Connector ID(s)     Filter(s)
#102   StaticMTRoute   0 (!)   smppc(connectorA)   <TG (tag=21401)>
#101   StaticMTRoute   0 (!)   smppc(connectorB)   <TG (tag=21403)>
#100   StaticMTRoute   0 (!)   smppc(connectorC)   <TG (tag=21425)>
#0     DefaultRoute    0 (!)   smppc(connectorD)
Total MT Routes: 4

MO Charging

In this case, the script is calling CGRateS charging system to check if user has sufficient balance to send sms, based on the following script, Jasmin will return a ESME_ROK if user balance, or ESME_RDELIVERYFAILURE if not:

"""This script will receive Mobile-Originated messages and
ask CGRateS for authorization through ApierV2.GetMaxUsage call.
"""
import json, socket
from datetime import datetime

CGR_HOST="172.20.20.140"
CGR_PORT=3422

def call(sck, name, params):
    # Build the request
    request = dict(id=1,
                    params=list(params),
                    method=name)
    sck.sendall(json.dumps(request).encode())
    # This must loop if resp is bigger than 4K
    buffer = ''
    data = True
    while data:
        data = sck.recv(4096)
        buffer += data
        if len(data) < 4096:
            break
    response = json.loads(buffer.decode())
    if response.get('id') != request.get('id'):
        raise Exception("expected id=%s, received id=%s: %s"
                        %(request.get('id'), response.get('id'),
                                response.get('error')))

    if response.get('error') is not None:
        raise Exception(response.get('error'))

    return response.get('result')

sck = None
globals()['sck'] = sck
globals()['json'] = json
try:
    sck = socket.create_connection((CGR_HOST, CGR_PORT))

    # Prepare for RPC call
    name = "ApierV2.GetMaxUsage"
    params = [{
        "Category": "sms-mt",
        "Usage": "1",
        "Direction": "*outbound",
        "ReqType": "*subscribers",
        "TOR": "*sms-mt",
        "ExtraFields": {"Cli": routable.pdu.params['source_addr']},
        "Destination": routable.pdu.params['destination_addr'],
        "Account": "*subscribers",
        "Tenant": "*subscribers",
        "SetupTime": datetime.utcnow().isoformat() + 'Z'}]

    result = call(sck, name, params)
except Exception, e:
    # We got an error when calling for charging
    # Return ESME_RDELIVERYFAILURE
    smpp_status = 254
else:
    # CGRateS has returned a value

    if type(result) == int and result >= 1:
        # Return ESME_ROK
        smpp_status = 0
    else:
        # Return ESME_RDELIVERYFAILURE
        smpp_status = 254
finally:
    if sck is not None:
        sck.close()

Overriding source address

There’s some cases where you need to override sender-id due to some MNO policies, in the following example all intercepted messages will have their sender-id set to 123456789:

"This script will override sender-id"

routable.pdu.params['source_addr'] = '123456789'

Note

Some pdu parameters require locking to protect them from being updated by Jasmin, more on this.

Activate logging

The following is an example of activating log inside a script:

"This is how logging is done inside interception script"

import logging

# Set logger
logger = logging.getLogger('logging-example')
if len(logger.handlers) != 1:
    hdlr = logging.FileHandler('/var/log/jasmin/some_file.log')
    formatter = logging.Formatter('%(asctime)s %(levelname)s %(message)s')
    hdlr.setFormatter(formatter)
    logger.addHandler(hdlr)
    logger.setLevel(logging.DEBUG)

logger.info('Got pdu: %s' % routable.pdu)

Enforcing DLR

Ask for DLR for all submit_sm pdus, no matter the downstream user choice, can be used for route qualification and scoring purposes.

"This script will enforce sending message while asking for DLR"

from jasmin.vendor.smpp.pdu.pdu_types import RegisteredDeliveryReceipt, RegisteredDelivery

routable.pdu.params['registered_delivery'] = RegisteredDelivery(
    RegisteredDeliveryReceipt.SMSC_DELIVERY_RECEIPT_REQUESTED)
language:python