Difference between revisions of "CAMEL proxy"
(→Script side) |
(→Yate side) |
||
| Line 503: | Line 503: | ||
On the Yate side, the ''camel_map'' module must be configured through ''camel_map.conf''. | On the Yate side, the ''camel_map'' module must be configured through ''camel_map.conf''. | ||
| − | In order for the module to ensure communication with the SSF, a section named | + | In order for the module to ensure communication with the SSF, a section named <tt>[local name_of_proxy]</tt> must be configured: |
[local proxyName] - what comes after ''local'' will be the name of the application | [local proxyName] - what comes after ''local'' will be the name of the application | ||
| Line 511: | Line 511: | ||
export_xml_as=both - how to export the XML part: string, object or both? | export_xml_as=both - how to export the XML part: string, object or both? | ||
| − | A | + | A <tt>[tcap name]</tt> section must be configured also. A section looks like this: |
[tcap scp] -- what comes after ''tcap'' will be the name of the translator | [tcap scp] -- what comes after ''tcap'' will be the name of the translator | ||
| Line 523: | Line 523: | ||
| − | For an external proxied SCF, additional | + | For an external proxied SCF, additional <tt>[local scfName]</tt> and <tt>[tcap name]</tt> sections must be configured: |
[tcap msc] | [tcap msc] | ||
| Line 540: | Line 540: | ||
| − | '''NOTE!''' In a proxy scenario, please check that you won't have a valid | + | '''NOTE!''' In a proxy scenario, please check that you won't have a valid <tt>[local crbt-scp]</tt> section configured in camel_map.conf. If so, this will allow to the camel_map module to catch messages emitted by the CRBT SCP that should have been catched by the proxy instead. |
Revision as of 14:40, 28 October 2013
The camel_proxy.php module provides functionality that allows that a single gsmSSF CAMEL invocation be proxied to multiple SCFs. The aim of this module is to provide a way of providing multiple CAMEL services on a single CAMEL request.
The main purpose is to be able to provide CRBT and PPS (PrePaid Service) facilities in parallel.
The layout for such a scenario will look like this:
What it basically does is that for one IDP invocation, the proxy will be able to translate it to multiple IDPs sent to multiple SCPs, either locally (like the CRBT one) or external. The proxy keeps an evidence of these multiple invocations and aggregates them into a single, valid dialogue with the invoking SSP.
Contents |
Camel Proxy Module Configuration
The configuration file is camel_bcsm_proxy.conf
Module configuration
'general' section
application: Application parameter in camel messages sent/handled for SSF dialogs.
This parameter is required and is not applied on reload (can't be changed after module starts).
gt: Global Title to be set in the first message sent in the SSF dialog.
This parameter is applied on reload.
TCAP address parameters to be set in the first message sent back to SSF can also be set using addr. prefix.
E.g. GT can be set as addr.CallingPartyAddress.gt along with other parameters like number nature addr.CallingPartyAddress.nature.
Setting the GT without other parameters is the same as:
addr.CallingPartyAddress.gt=[GT set]
addr.CallingPartyAddress.route=gt
addr.CallingPartyAddress.gt.encoding=bcd
addr.CallingPartyAddress.gt.translation=0
addr.CallingPartyAddress.gt.plan=isdn
addr.CallingPartyAddress.gt.nature=international
servicekey: CAMEL serviceKey to check when in received initialDP and set when forwarding them to SCFs.
Allowed interval: 0..2147483647.
Defaults to 0 if missing or invalid.
This parameter is applied on reload for new dialogs only.
query_scf: Boolean value indicating whether to query for proxied SCFs update when processing initialDP.
Is enabled a 'scf.query' message will be enqueued and the module will wait for a 'scf.response' message to continue IDP processing.
Defaults to no.
print_msg: boolean/string: Print sent/received messages to output if debug level is at least 9.
Allowed values are boolean values or 'verbose' string.
If verbose is specified, the message will be dumped on output.
Defaults to no.
print_xml: boolean/string: Print sent/received XML data to output if debug level is at least 9.
This parameter is ignored if print_msg is disabled.
Allowed values are boolean values or 'verbose' string.
If verbose is specified, XML elements' children, attributes or text will be shown on separate lines.
Defaults to no.
idp_calling_required: boolean: Calling party number is required (non empty) in initialDP.
Default to yes.
idp_called_required: boolean: Called party number is required (non empty) in initialDP.
Default to yes.
dispatcher_maxthreads: integer: Maximum number of message dispatch threads to use.
Set to 0 to enqueue messages using yate engine.
Defaults to 0.
When reloaded it can't be set to 0 (e.g. once set to a non 0 value it can be changed to non 0 values only).
Proxied SCF section(s)
enable: boolean: Enable the SCF.
Defaults to yes.
priority: integer: Priority in handling messages from SSF.
Defaults to 0.
servicekey: integer: Value with which the IDP serviceKey should be rewritten.
Allowed interval: 0..2147483647.
Defaults to SSF service key set in 'general' section.
dp: string: Comma separated list of detection points that should match the one received in IDP in order to contact this SCF.
Items may be DP value or name.
Defaults to termAttemptAuthorized if empty or all DPs are invalid.
endfatal: boolean: Indicate whether or not terminate the proxy dialog when this dialog ends.
Defaults to no.
errorfatal: boolean: Indicate whether or not an error or reject component from the SCF should terminate the whole proxy dialog.
Defaults to no.
local: boolean: The SCF is local (a local application) or external (it passes through the SS7 network to reach it).
Defaults to no (external application).
instances: integer: Number of local application instances.
This parameter is ignored for non local SCFs.
If non 0 it must be set to a value greater then 1.
Defaults to 0.
If non 0 the module will build the required number of SCFs and will pick them using a round-robin algorithm.
Each application's name will be built from SCF application name concatenated with instance suffix startting from 1.
E.g.:
[proxy SCP] instances=2
Will build 2 applications: SCP1 and SCP2.
handles: string: Comma separated list of operations received from the SSF accepted by this SCF.
Except ERB (Event Report BCSM), which is sent to all SCFs that match the reported DP, all operations that are handled by a SCF should be listed, otherwise the proxy will report to the SSF an error.
waittime: integer: Time, in miliseconds, to wait for a result from a SCF while being in Waiting For Instructions state, after which the dialog is aborted.
Defaults to 3000.
Minimum allowed value is 1000.
All other parameters starting with 'addr.' prefix will be put in dialog begin message sent for this SCF.
They should be set for non local SCFs.
Parameters:
- addr.CalledPartyAddress.route - string. It can be set to values: gt/ssn. It specifies how the SCCP address should be routed.
- addr.CalledPartyAddress.ssn - integer. It's the SSN number in case of SSN routing.
- addr.CalledPartyAddress.gt - string. GTT number digits for the SCF.
- addr.CalledPartyAddress.gt.encoding - string. It specifies the encoding for the GT digits. It is usually set to bcd.
- addr.CalledPartyAddress.gt.tt - integer. It specifies the GT translation type. It is usually set to 0.
- addr.CalledPartyAddress.gt.np - string. The GT numbering plan. It is usually set to isdn. It can be one of the following values: unknown, isdn, e164, generic, data, x121, telex, maritime-mobile, e210, e211, land-mobile, e212, isdn-mobile, e214, network-specific.
- addr.CalledPartyAddress.gt.nature - string. It specifies the nature of the GT number. It is usually set to international.It can have one the following values: unknown, subscriber, national-reserved, national-significant, international.
- addr.CallingPartyAddress.route
- addr.CalledPartyAddress.ssn
- addr.CallingPartyAddress.gt
- addr.CallingPartyAddress.gt.encoding
- addr.CallingPartyAddress.gt.tt
- addr.CallingPartyAddress.gt.np
- addr.CallingPartyAddress.gt.nature
Example
[general] application=camelProxy servicekey=1 gt=8820003 [proxy crbt-scp] servicekey=2 local=true [proxy pps-scp] servicekey=99 priority=2 errorfatal=true handles=applyChargingReport addr.CalledPartyAddress.gt=8820007 addr.CalledPartyAddress.route=gt addr.CalledPartyAddress.gt.encoding=bcd addr.CalledPartyAddress.gt.tt=0 addr.CalledPartyAddress.gt.np=isdn addr.CalledPartyAddress.gt.nature=international addr.CallingPartyAddress.gt=8820003 addr.CallingPartyAddress.route=gt addr.CallingPartyAddress.gt.encoding=bcd addr.CallingPartyAddress.gt.tt=0 addr.CallingPartyAddress.gt.np=isdn addr.CallingPartyAddress.gt.nature=international
camel_map configuration
[local camelProxy] translator=scp_proxy capabilities=Camel [tcap scp_proxy] type=CAMEL tcap=tcap_msc port=0 [local pps-scp] translator=scp_pps capabilities=Camel [tcap scp_pps] type=CAMEL tcap=tcap_pps port=0
camel_bcsm_proxy.conf.sample
; NOTE: This module is not loaded automatically, it needs a line in yate.conf:
; [postload]
; ${modulepath}/sig/camel_bcsm_proxy${modsuffix}=yes
[general]
; Unless explicitly specified, all parameters are applied on reload for new
; dialogs only
; All parameters starting with 'addr.' prefix will be put in the first message sent to SSF
; application: string: Application parameter in camel messages sent by the module
; This parameter is required
; This parameter is not applied on reload
;application=
; gt: string: Global Title to be set in the first message sent in the SSF dialog
; This parameter is applied on reload for new dialogs only
; If non empty other calling party address parameters will be set to default values
; This parameter can be overriden by addr.CallingPartyAddress.gt parameter
;gt=
; servicekey: integer: CAMEL serviceKey to check in received initialDP messages and
; set when forwarding them to SCFs
; Allowed interval: 0..2147483647
; Defaults to 0 if missing or invalid
; This parameter is applied on reload for new dialogs only
;servicekey=0
; query_scf: boolean: Query for proxied SCFs update when processing initialDP
; Is enabled a 'scf.query' message will be enqueued and the module will wait
; for a 'scf.response' message to continue IDP processing
; The response must return the list of SCFs to proxy
; The list may be shorter then configured SCFs
; New SCFs, other then configured ones, will be ignored
; The following SCF parameters can be overridden: priority, servicekey, errorfatal,
; handles, waittime and all parameters starting with 'addr.' prefix
; Defaults to no
;query_scf=no
; component_ttl: integer: Component time to live in milliseconds
; Minimum allowed value is 1000
; Defaults to 15000
;component_ttl=15000
; dialog_idle_ttl: integer: Dialog idle (nothing sent/received) time to live in milliseconds
; Minimum allowed value is 1000
; It can be set to 0 to keep it alive until the remote party terminates the dialog
; Defaults to 5000
;dialog_idle_ttl=5000
; dialog_ended_ttl: integer: Ended dialog time to live in milliseconds
; Minimum allowed value is 1000.
; It can be set to 0 to remove the dialog after termination
; Defaults to 0
;dialog_ended_ttl=0
; export_xml_as: string: Specify in which way the XML will be passed along into
; Yate messages
; Allowed values are:
; - string: pass the XML as a string
; - object: pass the XML as an object
; - both: pass the XML as a string and object
; Defaults to object
;export_xml_as=object
; print_msg: boolean/string: Print sent/received messages to output if debug
; level is at least 9
; Allowed values are boolean values or 'verbose' string
; If verbose is specified, the message will be dumped on output
; Defaults to no
;print_msg=no
; print_xml: boolean/string: Print sent/received XML data to output if debug
; level is at least 9
; This parameter is ignored if print_msg is disabled
; Allowed values are boolean values or 'verbose' string
; If verbose is specified, XML elements' children, attributes or text will be
; shown on separate lines
; Defaults to no
;print_xml=no
; idp_calling_required: boolean: Calling party number is required (non empty) in initialDP
; Default to yes
;idp_calling_required=yes
; idp_called_required: boolean: Called party number is required (non empty) in initialDP
; Default to yes
;idp_called_required=yes
; dispatcher_maxthreads: integer: Maximum number of message dispatch threads to use
; Set to 0 to enqueue messages using yate engine
; Defaults to 0
; When reloaded it can't be set to 0 (e.g. once set to a non 0 value it can be changed to
; non 0 values only)
;dispatcher_maxthreads=0
;dispatcher_priority: string: Default priority of message dispatch threads
; Can be one of: lowest, low, normal, high, highest
; High priorities need superuser privileges on POSIX operating systems
; Low priorities are not recommended except for debugging
; Defaults to 'normal'
; This parameter is applied on reload for new threads only
;dispatcher_priority=normal
;[proxy appname]
; This section configures a proxied SCF
; 'appname' is the application name to be used for the SCF
; enable: boolean: Enable the SCF
; Defaults to yes
;enable=yes
; priority: integer: Priority in handling messages from SSF
; Defaults to 0
;priority=0
; servicekey: integer: Value with which the IDP serviceKey should be rewritten
; Allowed interval: 0..2147483647
; Defaults to SSF service key set in 'general' section
;servicekey=
; dp: string: Comma separated list of detection points that should match the one received in IDP
; in order to contact this SCF
; Items may be DP value or name
; Defaults to termAttemptAuthorized if empty or all DPs are invalid
;dp=termAttemptAuthorized
; endfatal: boolean: Indicate whether or not terminate the proxy dialog when this dialog ends
; Defaults to no
;endfatal=no
; errorfatal: boolean: Indicate whether or not an error or reject component from
; the SCF should terminate the whole proxy dialog
; Defaults to no
;errorfatal=no
; local: boolean: The SCF is local (a local application) or external (it passes
; through the SS7 network to reach it)
; Defaults to no (external application)
;local=no
; instances: integer: Number of local application instances
; If non 0 the module will build the required number of SCFs and will pick them using a
; round-robin algorithm
; Each application's name will be built from SCF application name concatenated with instance
; suffix startting from 1
; E.g.
; [proxy SCP]
; instances=2
; Will build 2 applications: SCP1 and SCP2
; This parameter is ignored for non local SCFs
; If non 0 it must be set to a value greater then 1
; Defaults to 0
;instance=
; handles: string: Comma separated list of operations received from the SSF
; accepted by this SCF
; NOTE: Except ERB (Event Report BCSM), which is sent to all SCFs that match the reported DP,
; all operations that are handled by a SCF should be listed, otherwise the
; proxy will report to the SSF an error
;handles=
; waittime: integer: Time, in miliseconds, to wait for a result from a SCF
; while being in Waiting For Instructions state, after which the dialog
; is aborted
; Defaults to 3000
; Minimum allowed value is 1000
;waittime=3000
; All other parameters starting with 'addr.' prefix will be put in dialog begin
; message sent for this SCF
; E.g. addr.CalledPartyAddress.route=gt will be put as CalledPartyAddress.route=gt
Proxy Module Test
This chapter describes how the Camel Proxy module was tested.
The purpose of the test was to check if the Camel BCSM Proxy module can handle 100CPS.
The machine used was a Dual Intel Xeon E5620 (Quad Core with HT) = 16CPUs, 32GB RAM with CentOS 6.2
The setup was:
Yate1 - Call generator, sending calls to Yate3 using SIP
Yate2 - Call generator, sending calls to Yate4 using SIP
Yate3 - Call handling, send initialDP to Yate5 (Proxy)
Yate4 - Call handling, send initialDP to Yate5 (Proxy)
Yate5 - Camel BCSM Proxy
Yate6 - CRBT script
Yate7 - PPS script
Yate8 - PPS script
SIP M2PA link M2PA links
Yate1 ---------> Yate3 ------------| |-----------> Yate6 (CRBT)
| |
|-> Yate5 |-----------> Yate7 (PPS)
| |
SIP M2PA link | |-----------> Yate8 (PPS)
Yate2 ---------> Yate4 ------------|
NOTES:
- The sum of both call generators was 110CPS.
- During test top reported ~250%CPU for Proxy.
- All yate instances were running on the same machine.
- The reason of using 2 PPS instances was the performance of PPS script: 1 script is not able to respond quick enough. The PPS SCFs were rotated using 'scf.query' message.
How success was checked:
- On call generators all calls were answered
- On call handling instances (Yate3 and 4) there were no Tssf timeouts (this would indicate a timeout while waiting for instrunctions from SCP - after sending initialDP or eventReportBCSM with type='request')
- On Proxy instance (Yate5) there were no timeouts (this would indicate a SCF is not responding withing default 3 seconds interval)
Configuration
Script side
Configuration of the "camel_proxy.php" script is done through config_proxy.php. This allows setting the following parameters:
- 1 $myServiceKey - integer. The ID of the service provided by this gsmSCF application and which should come in IDP in order to accept the request.
- 2. $proxyName - string. It represent the value of the application parameter set in the camel.message coming from and going to the SSF. This value is used to check that the message is indeed intented for this script.
- 3. $mynum - string. GTT number assigned to this SCP.
- 4. $transTimeout - integer. It sets the time for which the PHP TCAP library will keep alive a TCAP dialogue after remaining with no active components. A new TCAP message will reset the associated timer. If the timer runs out, the library will generate a TCAP End in order to terminate the dialog. For this application, this timer is set by default to 180 seconds.
- 5. $scfs - array. This defines the list of configured proxied SCFs. Each entry in the array defines a SCF with its configuration parameters. The key set for the entry designates the name of the SCF and the value used for the aplication parameter set in the camel.message used to communicate between the proxy and the SCF. For each entry, the following parameters must be set:
- 5.1. serviceKey - integer. It represents the service key to be used when constructing an IDP for this SCF..
- 5.2. dp - string. It represent the detection point at which this SCF should be contacted. In order for the proxy to build an IDP for this SCF, the detection point received in the IDP from the SSF should match the one configured here.
- 5.3. priority - integer. It specifies the priority of this SCF when handling messages from SSF. According to priority,messages from the SSF will be passed by the proxy in priority order to the SCFs, first to the highest priority SCF (meaning the one with the lowest set value).
- 5.4. errorFatal - boolean. It specifies whether or not an error or reject component from this SCF should terminate the dialogue with the SSF and also with the other SCFs.
- 5.5. addr - array. It specifies SS7 network addressing parameters. They only need be set for external SCFs. Parameters are usually set here are:
- CalledPartyAddress.route - string. It can be set to values: gt/ssn. It specifies how the SCCP address should be routed.
- CalledPartyAddress.ssn - integer. It's the SSN number in case of SSN routing.
- CalledPartyAddress.gt - string. GTT number digits for the SCF.
- CalledPartyAddress.gt.encoding - string. It specifies the encoding for the GT digits. It is usually set to bcd.
- CalledPartyAddress.gt.translation - integer. It specifies the GT translation type. It is usually set to 0.
- CalledPartyAddress.gt.plan - string. The GT numbering plan. It is usually set to isdn. It can be one of the following values: unknown, isdn, e164, generic, data, x121, telex, maritime-mobile, e210, e211, land-mobile, e212, isdn-mobile, e214, network-specific.
- CalledPartyAddress.gt.nature- string. It specifies the nature of the GT number. It is usually set to international.It can have one the following values: unknown, subscriber, national-reserved, national-significant, international.
- CallingPartyAddress.route
- CalledPartyAddress.ssn
- CallingPartyAddress.gt
- CallingPartyAddress.gt.encoding
- CallingPartyAddress.gt.translation
- CallingPartyAddress.gt.plan
- CallingPartyAddress.gt.nature
- 5.6. local - boolean. It specifies whether the SCF application is found locally, inside the same Yate instance. If not, communication with the SCF means messages on the SS7 network.
- 5.7. handles - array. It specifies a list of operations that are handled by this SCF. Besides IDP and ERBE which are sent to all SCFs that match the sending criteria, other operation must be listed here in order for that SCF to receive it.
- 5.8. context - integer. The application context to be used in the dialogue with this SCF. If not set, the one received in the IDP from the SSF will be used.
- 5.9. waitTime - integer. It set the time, in seconds, for the proxy to wait for a result from this SCF while being in Waiting For Instructions state, after which the dialogue with that SCF is aborted, and proxy continues processing. Setting it to 0 means that the proxy will wait indefinetely.
A working configuration for camel_proxy.php looks like this:
$myServiceKey = "1";
$proxyName = "camelProxy";
/**
* GTT number of this SCP
*/
$mynum = "8820003";
/**
* Transaction timeout after inactivity
*/
$transTimeout = 180;
/**
* List of configured proxied SCFs
* The following parameters must be configured, all are mandatory:
* serviceKey - value with which the IDP serviceKey should be rewritten
* dp - detection point that should match the one received in IDP in order to contact this SCF
* priority - priority in handling messages from SSF
* errorFatal - whether or not an error or reject component from the SCF should terminate the whole proxy dialoque
* addr - SS7 network addressing parameters.
* local - whether the SCF is local (a local application) or external (it passes through the SS7 network to reach it)
* handles - lists operation received from the SSF that are accepted by this SCF.
* NOTE: Except ERBE, which is sent to all SCFs that match the reported DP, all operations that are handled by a
* SCF should be listed, otherwise the proxy will report to the SSF an error.
* context - if set, rewrites the application context for the dialog established with the SCF, otherwise leaves it as received
* waitTime - time, in seconds, to wait for a result from a SCF while being in Waiting For Instructions state, after which the dialogue
* is aborted.
*/
$scfs = array(
"crbt-scp" => array(
"serviceKey" => 2,
"dp" => "termAttemptAuthorized",
"priority" => 1,
"errorFatal" => false,
"addr" => array(),
"local" => true,
"handles" => array(),
"context" => "",
"waitTime" => 3,
),
"pps-scp" => array(
"serviceKey" => 99,
"dp" => "termAttemptAuthorized",
"priority" => 2,
"errorFatal" => true,
"addr" => array("CalledPartyAddress.gt" => "8820007",
"CalledPartyAddress.route" => "gt",
"CalledPartyAddress.gt.encoding" => "bcd",
"CalledPartyAddress.gt.tt" => "0",
"CalledPartyAddress.gt.np" => "isdn",
"CalledPartyAddress.gt.nature" => "international",
"CallingPartyAddress.gt" => "8820003",
"CallingPartyAddress.route" => "gt",
"CallingPartyAddress.gt.encoding" => "bcd",
"CallingPartyAddress.gt.tt" => "0",
"CallingPartyAddress.gt.np" => "isdn",
"CallingPartyAddress.gt.nature" => "international",
),
"local" => false,
"handles" => array("applyChargingReport"),
"context" => "",
"waitTime" => 3,
),
);
Yate side
On the Yate side, the camel_map module must be configured through camel_map.conf.
In order for the module to ensure communication with the SSF, a section named [local name_of_proxy] must be configured:
[local proxyName] - what comes after local will be the name of the application ;enable=no -- enable this application translator=scp - which translator should be used. A section named [tcap translatorValue] should be present in the config file. capabilities=Camel - capabilities supported by this application. CAMEL translator has only one capability and that is Camel. export_xml_as=both - how to export the XML part: string, object or both?
A [tcap name] section must be configured also. A section looks like this:
[tcap scp] -- what comes after tcap will be the name of the translator ;enable=no -- enable this translator tcap=tcap-scp -- TCAP to be used by the translator for SS7 network communication, a section with that name should be configured in ysigchan.conf host=0.0.0.0 -- address on which to listen for incoming applications port=0 -- port on which to listen for incoming applications. 0 means that will not build a listener, as the proxy works on messages. type=CAMEL -- type of translator (MAP/CAMEL). For the intended case, CAMEL should be set print-messages=true -- whether or not to print TCAP and XML messages in the logs add-encoding=false -- whether to add encoding attribute to data translated to XML
For an external proxied SCF, additional [local scfName] and [tcap name] sections must be configured:
[tcap msc] tcap=tcap-msc host=0.0.0.0 port=0 type=CAMEL print-messages=true add-encoding=false
[local ext-scp] ;enable=no translator=msc capabilities=Camel export_xml_as=both
NOTE! In a proxy scenario, please check that you won't have a valid [local crbt-scp] section configured in camel_map.conf. If so, this will allow to the camel_map module to catch messages emitted by the CRBT SCP that should have been catched by the proxy instead.
