Documentation

Revision as of 07:50, 11 December 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.

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.

x164 database

The x164 database stores CDRs, rating tables, route statistics and client information. From the web access you can easily manage the database and perform several tasks such as uploading rate tables, setting up credit limits for customers, and blocking bad routes.

Carriers and Customers are defined separately in their own tables, and they are linked to a profile in Profiles, which in turn is attached to a set of rates in the Rates table. A profile can be of type 'IN' (links customers to incoming rates), 'CARRIER' (links carriers to outgoing rates ), or 'DIDRANGE' (routes that terminate in your own network). DID numbers are defined in DIDcients. The table relationship is as follows:

It is possible to allow the user to choose dynamically between different rate sets by using prefix dialing. This is accomplished by creating many instances of the same incoming profile and setting a different rate name and prefix for each one of them. Rates associated with this profiles will only be available when dialing the prefix. A more detailed explanation can be found here.

Currencies sets the exchange rate to euros for each currency. When looking up routes, the field 'curr_code' in Profiles links to the matching exchange rate, and the price for routes is normalized according to it.

Finally, monthly credit limits for subscribers can be set in the Quota table. This table keeps record of the monthly bill sum for each subscriber. If a quota is set and the limit is reached, the subscriber is blocked. This means the field 'blocked' of its entry in the Customers or Carriers table is set to 1. Unblocking must be done manually.

x164 Call flow

When receiving a call, the softswitch queries the database for user authentication using the Authuser procedure. The flag 'Dynamic_IP' in Customers indicates if the customer uses fixed or dynamic IP. In the first case, authentication is made by IP. In the second, the fields 'Subscriber' and 'Password' are used.

If the authentication is positive, the softswith calls the Preroute procedure to check that the user is allowed to call the dialed number. The user's profile is linked to a set of rates that define the allowed destinations. If there is a match between the called number and one of this rates, the softswitch looks up the database for outgoing rates.

Outgoing rates are retrieved with the Route procedure. The algorithm retrieves the rates with the longest code match for each carrier, and calculates their profitability. Only rates that generate revenue are returned. The softswitch attempts to route the call using this rates, starting from the most to the least profitable until the call is effectively routed.

When the call finishes, a CDR is created and the rate's statistics are updated with the cdr_finalize procedure.

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

The call search offers access to Call Detail Records (CDRs). CDRs can be summarized and filtered for various statistics.

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 introduces ​​in this tables.

Customers table

The Customers table shows details of your authorized users who may send calls through the x164 system. Customers can be authorized by Trusted Peer when they use fixed IP or Subscriber and Password for dynamic IP users.

Customers are linked to incoming profiles via the Profile field. In turn, this profiles link to a set of incoming rates that determine the destinations that the customer is allowed to call.

When a customer number is within a DID block, the Subscriber field links to an entry in the DIDclients table that defines the user's number. This field is also used to set up quota limits for customers in the Quota Usage table.

Carriers table

The Carriers table has the details of your carriers to send calls to them. A carrier has an unique 'CARRIER' profile, which is attached to its available outgoing rates. Carrier_name can be used to set a quota limit in the Quota usage table.

Profiles table

The Profiles table links customers, carriers and DID blocks to their respective rates. It also sets rate plan details such as valid week hours, minimum charged price, and currency in which the rates are expressed.

There are three type of profiles: 'IN', 'CARRIER' and 'DIDRANGE'. 'IN' profiles link customers with incoming rates. The field Tech_prefix is used in 'IN' profiles to enable prefix dialing, as explained here.

'CARRIER' profiles link carriers with outgoing routes. A carrier may have several rate plans and different time frames and penalties can be set for each of them.

'DIDRANGE' is used to define blocks of own numbers. The range is defined in the Rates table, and customers with numbers within this range are set in the DIDclients table.

Rates table

The Rates table contains the rate information used by x164 to pick routes and calculate tariffs. Statistics for call duration and success rate are stored here and updated in real time every time a rate is used.

All prices must be defined as the original price multiplied by ten thousand. For example, for a rate of 0.1234 Euros, the input price in the x164 system should be 1234.

Gateways table

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

DIDclients table

DIDclients is used to associate a DID number with a subscriber. When a call is being routed and the retrieved rate is attached to a 'DIDRANGE' profile, the system refers to this table to identify the subscriber who owns the number. See how to set up a DID subscriber here.

Currencies table

The currencies table shows the currencies used by x164 system. Profiles are linked to records in this table by the Curr_code field. In the routing process, all the rates retrieved for a destination must be exchanged to the same currency to decide which one is the most profitable.

Quota table

The quota table is used to set monthly credit limits for subscribers. It keeps track of the monthly bill sum and blocks the subscriber when it reaches the amount specified in Quota. Here you can find more information.

Generation of client rate tables

x164 allows to generate rate tables for customers from outgoing carrier rate tables. x164 consolidates the carrier rates into one rate table following a strict longest-code-match logic. The rate table can be further simplified by filtering for quality or consolidating prices within tolerances to one code/price.

The operation takes the following parameters as inputs:

In the first step all outgoing rates are retrieved, filtering by date and reseller id. The reseller id is found in the Gateways table using the secret_key parameter. The relationship with the Rates table is defined as folows:

Then the algorithm looks for the cheapest price for each destination, filtering out the rates that don't satisfy the ACD and ASR minimums. If there is no rate that satisfies this limit for a given destination, the rate with the best quality is chosen.

At the end of this process there will be one record for each destination dialing code. Before starting with the simplification stage, all records with price lesser than rateMin are set to rateMin.

In the next steps, rates will be simplified using the tolerance parameter. First, redundant codes will be removed if shorter codes exist within their price tolerance. As an example, consider the following records:

Destination	Price
371660		25
3716		28

With a tolerance of 15%, the record for 371660 would have a price range [22.5 - 28.5]. Since the shorter code 3716 is within this range, 371660 is considered redundant and deleted from the final table.

In the second part of the simplification process, the algorithm groups sets of ten consecutive codes, like the following:

Destination	Price
3710		50
3711		50
3712		45
3713		51
3714		47
3715		48
3716		49
3717		50
3718		47
3719		46

First the system makes sure the shorter code (371) does not already exist in the database. If it doesn't, it checks that all the prices are within the tolerance range. In the previous table case, for a tolerance of 15%, the cheapest price upper limit would be 45*(1+15/100) = 51.75, which is superior to the highest price in the set. Thus, this set is removed from the final table and a new record is created, using the information of the most expensive code, and updating the destination field to the one that comprehends the whole set:

Destination	Price
371		51

Once the simplification process is over, codes longer than max_code_length are deleted. Finally, all the prices are increased according to the profit percentage specified in the input.

CSV import and export

The x164 system supports CSV import and export to ease the task of updating the rating tables. CSV files are plain text files which store spreadsheet or database information. In the x164 system semicolons (;) are used to separate fields, and line breaks separate records. Rating related information will frequently be available in some spreadsheet format, so in order to upload it to the x164 database you will need to export to CSV first.

Import a CSV file to the database

We will use OpenOffice Calc for this example, although the process is similar in other spreadsheet softwares like Excel. First step is to reorder your data to fit the x164 format. The necessary fields for each table are the following:

Customers:

Carriers:

Profiles:

Rates:

DIDclients:

Note that in the formats field each format must be separated by a dot (.) instead of a comma.

The 'ops' field determines the action to be taken:

ops	Action
1	Insert new records.
2	Match records and update.
3	Match records and delete.

Take as an example the following rates table:

Country Country Dial Code Bronze $ USD Effective Date StatusAfghanistan 93 0.17040 Oct 09, 2012 New LocationAfghanistan Cellular-AT 9375 0.15225 Oct 09, 2012 New LocationAfghanistan Cellular-AWCC 9370 0.13388 Oct 09, 2012 New LocationAfghanistan Cellular-Areeba 9377 0.14700 Oct 09, 2012 New LocationAfghanistan Cellular-Etisalat 9378 0.16188 Oct 09, 2012 New LocationAfghanistan Cellular-Others 937 0.13965 Oct 09, 2012 New LocationAfghanistan Cellular-Roshan 9379 0.14490 Oct 09, 2012 New LocationAlbania 355 0.08190 Oct 09, 2012 New LocationAlbania Cellular-AMC 35568 0.20790 Oct 09, 2012 New LocationAlbania Cellular-Eagle 35567 0.21105 Oct 09, 2012 New LocationAlbania Cellular-Plus 35566 0.21105 Oct 09, 2012 New LocationAlbania Cellular-Vodafone 35569 0.16082 Oct 09, 2012 New LocationAlbania,Tirana 355422 0.08558 Oct 09, 2012 New LocationAlbania,Tirana 355423 0.08558 Oct 09, 2012 New LocationAlgeria 213 0.03900 Oct 09, 2012 New LocationAlgeria Cellular 2136 0.15500 Oct 09, 2012 New LocationAlgeria Cellular-Djezzy 21377 0.16000 Oct 09, 2012 New LocationAlgeria Cellular-Djezzy 213780 0.16000 Oct 09, 2012 New LocationAlgeria Cellular-Djezzy 213781 0.16000 Oct 09, 2012 New LocationAlgeria Cellular-Djezzy 21379 0.16000 Oct 09, 2012 New LocationAlgeria Cellular-Wataniya 2135 0.18000 Oct 09, 2012 New LocationAlgeria,Algiers 21321 0.03900 Oct 09, 2012 New LocationAmerican Samoa 1684 0.02964 Oct 09, 2012 New LocationAmerican Samoa (old) 684 0.00672 Oct 09, 2012 New LocationAmerican Samoa Cellular 16842 0.02964 Oct 09, 2012 New LocationAmerican Samoa Cellular 168473 0.02964 Oct 09, 2012 New LocationAndorra 376 0.01920 Oct 09, 2012 New LocationAndorra Cellular 3763 0.13860 Oct 09, 2012 New LocationAndorra Cellular 3764 0.13860 Oct 09, 2012 New Location

Create a new spreadsheet where the first row contains the field names for the relevant x164 table.

Insert your data in the appropiate fields of the new spreadsheet. Note that the x164 system works using the price multiplied by ten thousand, so you will have to convert it first.

ops	Reseller   Rate		Destination   Region	Description	App	Conn	Price	Conn In	Price In  Start Date  End Date
1	100	   Rate_Name	34			Spain		Audio		2580			  09-10-2012
1	100	   Rate_Name	34928			Spain		Audio		1757			  09-10-2012

Note that CSV files use line breaks to separate records and commas to delimit fields. You must ensure those are not present in your data.

To export the spreadsheet to a CSV file in OpenOffice, simply go to File -> Save As and select "Text CSV (.csv)". In the opened dialog you must rename the file with the name of the destination table, an underscore '_' and a number.

rates_1.csv		// CSV file names example for the Rates, Carriers and Profiles tables.
carriers_25.csv
profiles_81.csv

In the x164 web access, go to the destination table and click on 'Choose a file'. Select your file and click 'Import'. When the file is correctly uploaded a confirming message will be prompted. The imported data will be available after a few minutes.

Export x164 table to a CSV file

You can also export data from the database in CSV format by clicking on the 'Export table.csv' button on the right side of a table. A new browser window will be opened showing the CSV text.

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 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 Profiles 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

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

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

Mysql database module - mysqldb.conf

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

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

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

User_Auth is used to identify the subscriber.

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

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

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

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

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

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

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

Preroute

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.

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

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

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
)

Route V2

Selects the possible outgoing routes according to the incoming parameters. It also allows to select the routing method, set quality limits, and enable loss making calls.

PROCEDURE `proc_get_route_v2`( 
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
IN routing VARCHAR(100),		// Routing method: 'least_cost', 'quality'. Default is profit based routing.
IN qACD INT,				// Minimum Average Call Duration. Routes below this limit are blocked.
IN qASR INT,				// Minimum Success Rate (successful calls/total calls). Routes below this limit are blocked. 
IN blocklosscalls TINYINT(4))		// 0/1 flag, blocks unprofitable calls when 1
)

cdr_finalize

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

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

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

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

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