Documentation

From x164 documentation wiki
(Difference between revisions)
Jump to: navigation, search
Line 13: Line 13:
 
==x164 Call flow==
 
==x164 Call flow==
  
When receiving a call, the softswitch queries the database for user authentication, which can be made either by IP for fixed IP suscribers or user/password for dynamic IP subscribers. If the authentication is positive, the system preroutes the call. This means a new query is issued to verify if there is an incoming rate linked to the user to call the dialed number. Each user is linked to a profile that includes a set of incoming rates. Additionally, a prefix can be used to choose between different incoming profiles when making a call. If no tariff is returned, the call is blocked.
+
When receiving a call, the softswitch queries the database for user authentication, which can be made either by IP for fixed IP suscribers or user/password for dynamic IP subscribers. If the authentication is positive, the system preroutes the call. This means a new query is issued to verify if there is an incoming route linked to the user for the dialed number. If no tariff is returned, the call is blocked.
  
Then the softswitch queries again the database to retrieve all the possible outgoing routes/rates for the call. With this information it calculates the most profitable rate, taking in account not only the routes cost, but also statistical information about the amount, success and duration of the calls made in the past using them.
+
If a tariff is returned, the softswitch queries again the database to retrieve the outgoing routes/rates for the call. Again, if there is no outgoing rate defined for the called number, the call will be blocked. Otherwise, the system chooses the most profitable rate, taking in account not only the routes cost, but also statistical information about the amount, success and duration of the calls made in the past using them.
  
 
When the call finishes the softswitch updates both the CDR database and the routes/rates/statistics database.
 
When the call finishes the softswitch updates both the CDR database and the routes/rates/statistics database.

Revision as of 10:42, 26 September 2012

Here are a few links you can start from. In addition, you might want to take a look at the list of all categories or all pages.

Contents

x164 Introduction

x164 consists of a central database which holds private and public rate tables, statistics and route configurations. Many x164 switches connect to the central x164 database to retrieve routing information and to update the statistics in realtime. Softswitches are preferably, but not limited to, yate-based switches. Call detail records are collected with radius. Call details, statistics and the configuration screens are accessible by the web access.

X164system.png

x164 Rates database

Customers are linked to incoming profiles, which in turn link to an unique set of rates or many. In the latter case, many profile entries are defined with the same name and a different prefix. The prefix will be used by the customer to select between different incoming rate sets when making a call. Every carrier is linked to an only profile. With this profile you define the rates offered by the carrier to route your outgoing calls. Rates set the tariff for a given range of numbers.

x164 Call flow

When receiving a call, the softswitch queries the database for user authentication, which can be made either by IP for fixed IP suscribers or user/password for dynamic IP subscribers. If the authentication is positive, the system preroutes the call. This means a new query is issued to verify if there is an incoming route linked to the user for the dialed number. If no tariff is returned, the call is blocked.

If a tariff is returned, the softswitch queries again the database to retrieve the outgoing routes/rates for the call. Again, if there is no outgoing rate defined for the called number, the call will be blocked. Otherwise, the system chooses the most profitable rate, taking in account not only the routes cost, but also statistical information about the amount, success and duration of the calls made in the past using them.

When the call finishes the softswitch updates both the CDR database and the routes/rates/statistics database.


CallFlow.png X164scheme.png

Web Access

x164 provides its members a web access to configure their settings, upload their rate tables and view call statistics. The interface and rating-engine is derived from CDRTool, which we modified heavily for speed and simplification.

Call search menu

Description

The call search offers access to call-detail-records CDRs. CDRs can be summarized, filtered for various statistics.

Selection fields

Data source Database where are the call details
Start time Beginning of the range of time in search
Stop time End of the range of time in search
Sip call / Sip source Filter by the user ID, received from the customer or proxy
User agents / Media code Filter by the format of the call
Sip Billing Party (username) Search the calls of a subscriber
Sip Caller Party (From URI) Filter using the ID received from the caller
Sip destination (Canonical URI) Filter by destination of the call
Duration / Application / status Filter selecting different call duration, media or the status of the call
Order by / Group by Complements the search ordering results, change the limit of records to show, grouping these and if ReNormalize is marked the system recalculate the call prices

Rating menu

Access to all data influencing the rating and routing. The rating data is contained in several tables which can be selected on the top-right side. The cost calculation of the calls stored in the system occurs in parallel and periodically using the values that the user introduce ​​in this tables.

Customers table

Description

The Customers table shows details of your authorized customers who may send calls through the x164 system, the user can be authorized by trusted peer or subscriber and password.

Data fields
Id Automatically generated id field
Reseller Numeric ID of reseller
Trusted Peer Authorized IP address, in this case the user is authorized by IP
Domain Not used
Dynamic_ip Use dynamic IP when value set to 1
Subscriber Subscriber name in the format "user@domain" used as billing party in the rate process
Password Password for authorized users
Profile Profile name which links the customer to a profile in the profile table
Subscriber_out In case subscriber also provides outgoing routes put outgoing subscriber name here to avoid looping calls
Blocked Block the subscriber when value set to 1
Pre_location Parameters that are added before the called number in the outgoing message (possible values: SIP/00 to identify a SIP carrier with prefix of 00 in front of the e164 number)
Post_location URL and parameters added to the called number in the outgoing message, e.g. @carrier.com
The outgoing route is defined as: pre-location + e164 number + post-location, e.g. SIP/004930123456789@carrier.com
Expires Expiration time of the dynamic IP
Formats Possible codec formats separated by comma (possible values: g729, ulaw, alaw, t38)
rtpProxy 1 activates rtp proxying for this route

Carriers table

Description

The Carriers table has the details of your carriers to send calls to them.

Data fields
Id Automatically generated id field
Reseller Numeric ID of reseller
Domain Not used
Carrier_name Carrier name in the format "user@domain" used as billing party in the rate process
Profile Profile name which links the customer to a profile in the profile table
Blocked Block the subscriber when value set to 1
Pre_location Parameters that are added before the called number in the outgoing message (possible values: SIP/00 to identify a SIP carrier with prefix of 00 in front of the e164 number)
Post_location URL and parameters added to the called number in the outgoing message, e.g. @carrier.com
The outgoing route is defined as: pre-location + e164 number + post-location, e.g. SIP/004930123456789@carrier.com
Line Section identifier from accfile.conf, this can be used instead of pre-location, post-location
Formats Possible codec formats separated by comma (possible values: g729, ulaw, alaw, t38)
rtpProxy 1 activates rtp proxying for this route

Profiles table

Description

The profiles table shows the rate details assigned to customers which will be used to calculate the price of the call by x164 system,

Data fields
Id Automatically generated id field
Reseller Numeric ID of reseller
Profile Profile name which links the customer to the profile table
Rate Rate name which identifies the rates used for this profile in the rates table
Starthourweek Start hour in the week of this tariff (possible value range 0 - 167) 0 hour is Sunday 0:00 hour in local time
Endhourweek End hour in the week of this tariff (possible value range 0 - 167) 0 hour is Sunday 0:00 hour in local time
Penalty Constant price added to this rate. Used to penalize a tariff.
Timezone Timezone must reflect the local time of the tariff in the rating profile table. The setting is used to correct the CDR timestamps coming from the softswitch which should be in GMT time. Use timezone identifier.
Incr Used to consider the duration of the call in increments (default 1 second)
Min_Dur Minimum duration time charged of the call, only activated when the call is successful
Curr_code Currency used in iso format (EUR, USD ...), if you want use your own values the format should be iso and adding reseller number
Carrier possible profile types:

IN : for incoming routes
CARRIER: for outgoing carrier routes
DIDRANGE: defines a block of own numbers, numbers within such blocks are only routed to clients with DIDs

Tech_Prefix Technical prefix used to identify incoming rate table. Different tech prefixes allow to link several rate tables to one incoming customer, e.g. to let the client chose dynamically grey, standard, premium rate tables. Prefixes must have two digits and when dialing they are used as follows: (prefix)#(called number)

Rates table

Description

The rate table shows details to calculate the price by x164 system according to valid tariff and destination

Data fields
Id Automatically generated id field
Reseller ID number
Rate ID of the rate
Destination Destination number to this rate
Region Region of this number
Description Description of the destination to the number
App Application Type: audio, sms
Conn Price of the call connection
Price Price per minute
Conn In Cost of the call setup, to calculate the profit of the call
Price In Cost per minute, to calculate the profit of the call
Start Date The start time of the rate
End Date The end time of the rate
Blocked Lock indicator of the rate
Billtime_sum Sum of billed time of this rate
Ringtime_sum Sum of ring time of this rate
Setuptime_sum Sum of setup time (until ringing) of this rate
Calls_count Number of calls of this rate
Success_count Number of connected calls
Acd_short Short-term average call duration, updated after each call with acd_short = ((5 * acd_short) + _billtime)/6,
Acd_avr Long-term average call duration, updated after each call with acd_avr = (acd_short + (billtime_sum / success_count)) / 2

Gateways table

Description

The gateways table serves to identify the IP address of the switches used by the reseller.

Data fields
Id Automatically generated id field
Reseller ID number
Gateway IP address of the switch
Secret Switch's password

DIDclients table

Description

The DIDclients table show the DID clients with their numbers.

Data fields
Id Automatically generated id field
Reseller ID number
DID_number Number of the client
DID_subscriber Subscriber who belongs this number

Currencies table

Description

The currencies table shows the currencies that use by x164 system to can evaluate in routing process to look for the most appropriate route.

Data fields
Id Automatically generated id field
Reseller ID number
Domain Not used
Currency Currency id in the system, use ISO format adding reseller number to be unique in the system
Curr_rate Value of the currency, against the euro

Quota table

Description

The quota table stores the billed sum of calls made by each subscriber. The table allows to set a monthly quota limit. When the limit is reached the subscriber is blocked. The usage is reset at the beginning of each month. Un-blocking of subscribers has to be done manually.

Data fields
Id automatically generated id field
Reseller ID number
Subscriber Subscriber name in the format "user@domain"
Domain Subscriber domain
Quota Quota limit per month
Notified Date on which the system detected the exceeded limit
This Month Monthly cumulative consumption
Today Daily cumulative consumption

Softswitch

The x164 switch is based on yate, In its basic configuration the switch can handle SIP and H323 calls. IAX, ISDN, SS7 calls are theoretically possible. Users can activate further yate modules to extend the possibilities. x164 members are encouraged to post their suggestions and ideas on the [ http://forum.x164.com/ forum]. The yate configuration is located in /usr/local/etc/yate.

Server settings

Time zone

The server running yate should have its timezone set to GMT time if the timezone setting is used in the rating customers table. The timezone setting in the rating customer table must reflect the local time of the tariff in the rating profile table. The timezone setting is used to correct the CDR timestamps coming from the softswitch. The Starthourweek and Endhourweek time ranges in the rating profiles table are always in local time.

CDR module - cdrbuild.conf

Description

This module builds the CDR messages (Call Details Record) which are used later in the radius module. Here are set the necessary attributes to create the correct CDR messages.

h323 Channel module - h323chan.conf

Description

This module give support to h323 protocol by using the open h323 library.

Mysql database module - mysqldb.conf

Description

This module is used to make the connection between yate and a MySQL database. Establishing the necessary parameters as host, port, database and password.

Radius module - yradius.conf

Description

This module give support to establish communication between Yate and FreeRADIUS, as well the ip address and port of the FreeRADIUS server. Are set the specific attributes to sent in the CDR message and are assigned the correct values.

Regexroute module - regexroute.conf

description

This module is used in addition to the register module, to assign values ​​of different parameters in the call as the error messages or the formats to use in transcoding calls, used to route calls without using database.

Register module - register.conf

The register module defines the messsage handlers which are communicating with the x164 database. Message handlers "catch" internal yate messages, issue queries to the database and return the result back to yate. x164 is configured to use mysql stored-procedures as message handlers.

Authuser

Description

User_Auth is used to identify the subscriber.

Statement
PROCEDURE `proc_user_auth`( 
IN username VARCHAR(100),   // username received in SIP INVITE
IN domain VARCHAR(100),     // domain name from caller
IN address VARCHAR(25)      // IP address and port of the received call
IN password VARCHAR(25)     // secret key for MySQL procedures in Yate
)

Register

Description

This query handle register messages, add in database data of register users and the last time that the user was registered.

Statement
PROCEDURE `proc_user_register`( 
IN ip_host VARCHAR(30),         // IP address received in SIP INVITE
IN ip_port INT,                 // IP port received in SIP INVITE
IN expires INT,                 // register expiration time
IN authname VARCHAR(125)        // authorized subscriber name corresponding in data base
 IN password VARCHAR(25)        // secret key for MySQL procedures in Yate
)

Unregister

Description

This query handle unregister messages initializing the data entered by register message.

Statement
PROCEDURE `proc_user_unregister`(
IN authname VARCHAR(125)        // authorized subscriber name corresponding in data base
 IN password VARCHAR(25)        // secret key for MySQL procedures in Yate
)

Engine timer

Description

The engine timer found that users have exceeded the time of registration and invalidate the dynamic_ip.

Statement
PROCEDURE `proc_user_enginer_timer`(
IN password VARCHAR(25)       // secret key for MySQL procedures in Yate
)

Preroute

Description

Preroute checks whether an incoming route for the combination of IP address and called number or authname and called number exists. The caller is either identified by IP address or was identified by authname/password combination in authname procedure. If no incoming route exists the call is blocked.

Statement
PROCEDURE `proc_get_preroute`( 
IN authname VARCHAR(125),     // authorized subscriber name corresponding in data base
IN address VARCHAR(25),       // IP address and port received in SIP INVITE
IN called VARCHAR(100)        // the called number, optionally with prefix
IN password VARCHAR(25)       // secret key for MySQL procedures in Yate
)

Route

Description

This selects the possible outgoing routes according to the incoming parameters, looking for the best quality and profit.

Statement
PROCEDURE `proc_get_route`( 
IN usernameNobuy VARCHAR(125), // Subscriber_out found in incoming route to prevent call loops
IN rtproxy_in TINYINT(4),      // 0/1 flag to specify whether the rtp stream of the incoming call leg is proxied.
IN realRateSell FLOAT,         // (client) call rate found in preroute expressed in the base currency (EUR) 
IN called VARCHAR(100),        // Called number (optionally with prefix). The prefix is not used.
IN _format_in VARCHAR(255),    // Codecs received in incoming call leg
IN password VARCHAR(25)        // secret key for MySQL procedures in Yate
)

cdr_finalize

Description

This procedure computes the values ​​of the call once finished to update the statistics in the system.

Statement
PROCEDURE `proc_cdr_finalize`( 
IN duration FLOAT,         // the overall call duration
IN billtime FLOAT,         // the time the call was connected
IN ringtime FLOAT,         // duration of call ringing
IN direction VARCHAR(10),  // incoming or outgoing
IN status VARCHAR(10),     // if the call was connected or not
IN rateidBuy BIGINT(20),   // id of the rate for the outgoing call leg
IN rateidSell BIGINT(20),  // id of the rate for the incoming call leg
IN password VARCHAR(25)    // secret key for MySQL procedures in Yate
)

RTP Channel module - yrtpchan.conf

Description

This module provides RTP and udptl transports for any technology that requieres it as SIP or H.323. The RTCP support is disabled.

SIP Channel module - ysipchan.conf

Description

This module give support to SIP protocol using the YASS library. Here also is posible select the value "expires" used in register.conf and the codecs enable to use.

Yate - yate.conf

Description

In this configuration file is selected the modules that are in use, and the parameter "timeout" limits the call duration as 2h.

Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox