LCDial.sh AGI script

LCDial.sh AGI script evolves into LCDC: the Least Cost Dialplan Compiler

Product End-of-Life Announcements

No new versions of LCDial.sh should be expected, as the product has now been superseded by the LCDC, the Least Cost Dialplan Compiler: much faster and more portable, as it allows to find the least cost route directly in the dialplan, without involving AGI. Try it, it's great!

Synopsis

AGI script, written for the shell interpreter ash, that performs an ASCII flat file lookup to find the cheapest Provider for a given destination number, and then invokes the Dial command, similarly to the Application LCDial (but without MySQL or any other database!). Also, an ENUM lookup is always automatically attempted before considering the actual providers (this requires the proper configuration of Asterisk's enum.conf).

Description

  • LCDial.sh(number_to_dial,timeout,options,URL,maxcost[,conffile][,announce.sh]) — dial one channel

Parameters:

  • number_to_dial specifies the number which should get dialed.
  • "timeout", "options" and "URL" are the same as within the standard Asterisk cmd dial command (they are directly passed to the dial comand).
  • "maxcost" is an optional value, expressed in millicents (thousandths of a cent), that puts a ceiling to the acceptable cost per minute for the call being initiated.
  • "conffile" is an otional "per-call" custom configuration file, replacing the default LCDial.sh.conf
  • "announce.sh" is an optional announcement script played just before attempting a "Dial()"

Return codes

Always returns 0, and with the ${DIALSTATUS} variable set by the last Dial internally executed (see Asterisk cmd dial).

Example:
exten => 4000,1,AGI(LCDial.sh,${EXTEN},15,,,14500)

...will ignore any route costing more than 14.5 cents per minute.

Installation, configuration and use

See this file.

NEW in version 1.1: Routes with the same cost are sorted based on the provider's position in the configuration file. This allows to enforce preferences, listing preferred providers before less desirable ones. Also, added to the package the "finareafreecoverage" script that prints, based on the information contained in the p_ and c_ files, the free routes comparative table shown at Finarea SA.

NEW in version 1.0: added optional parameter to specify the pathname of a shell script that will be run just before Dial(), typically to play an announcement of the call's cost. A sample /usr/lib/asterisk/agi-bin/announce.sh is included.

NEW in version 0.9: limited to free routes only, a MUCH faster alternative that does not use AGI is now available: see the doc file in the section describing how to use the utility "buildfreeroutes".
(Bugfix in version 0.8a: exended compatibility to old versions of ash that do not support "$((...))" arithmetic expansion; also, checkrates.cgi now works again.)

NEW in version 0.8: automated generation of ratefiles from provider description files (p_ files) and country files (c_files). Useful particularly for quickly updating the configuration to reflect the "free destinations" offered by some providers. NOTE: as "exclusion" rate, "9999999" must now be replaced by "!" (for all the details, see the doc file).

(BugFix in version 0.7a: replaced flaky open_r/close_r code with safer alternatives; gzip-compressed country.csv file used by checkrates.cgi; updated some rate files.)

NEW in version 0.7: possibility of specifying alternate configuration files on per-call basis; possibility to flag providers as "only providing routes more expensive than NNN millicents/minute", so to achieve a speed optimization when looking only for cheap or free routes (see doc file).
Also, a simple "Rate checker" web app written in Haserl (OpenWRT version available) to compare the rates to a given destination from the termination providers installed in LCDial.sh.conf . Of course, LCDial.sh will try them in reverse cost order.

(BugFix in version 0.6a: a missing "-n" option to sort caused incorrect results with GNU sort, although not with Busybox' sort. Many thanks to Marat Gulevich for spotting this!)

(BugFix in version 0.6: Now the script also works with bash as shell, not only with ash. Also, added rate table for VoipStunt.)

BugFix in version 0.5a: a few fixes to various ratefiles; Sixtel's removed altogether, due to their dismal service. Also, the gatherer scripts for VoipJet and Teliax now avoid unnecessary writes to flash memory if the respective rate files are found not to have changed. This means that you may safely invoke those gatherers more often.)

NEW in version 0.5: two ash scripts that can be started as cron jobs to build automatically updated rate files for Teliax and VoipJet (my preferred PSTN termination providers), after harvesting the necessary information from the .csv documents made available on the respective websites. (I would create one also for Voxee, if they did not make available only a silly Excel file, with several screwed-up entries to boot...).

(BugFix in version 0.4b: the format of the dial channel derived from ENUM lookup through dig was incorrect, and has been fixed. Also: a NOANSWER within 5 seconds of dialing and an ANSWER within 20 seconds are now treated as CHANUNAVAIL, and the next route is tried. Finally, fwdout has been added as (free) provider.)

(BugFix in version 0.4a: in /etc/asterisk/lcdialsh/LCDial.sh.conf , "voipbuster.com" was wrong, and has been corrected into "voipbuster" . In order to authenticate with the peer, Dial()'s parameters should always contain references to accounts defined in iax.conf or sip.conf, not to hosts.)

NEW in version 0.4: lines in the rate files may be commented out by '#' or ';' characters (actually, anything on the line after those characters will be ignored). ALSO, the lines in the configuration file may now specify an optional fourth field, a "number-to-postdial digits" rule, useful for dialing through FXO ports using call cards or cheap/free phone-to-phone IDD services (for instance, Finarea's HongKongCall.com or, in UK, DialWise.co.uk).

NEW in version 0.3: each line in the rate files may now optionally contain additional integer parameters representing start time, end time and weekdays of the interval when that rate applies (see docs).

NEW in version 0.2: if dig is installed, it is used to retrieve all the ENUM NAPTR records rather than only the first through Asterisk's EnumLookup (see docs).

Getting it

Here is an ipkg package for installation on embedded platforms such as OpenWRT; it may also be opened e.g. with "tar -zxf" or, under Windows, 7Zip and installed manually. It includes documentation, sample configuration file and a few sample rates files (please read the disclaimer in the README.txt).
Please note: on platforms other than OpenWRT, some paths are likely to be different: in particular, /usr/lib/asterisk/... will probably have to be changed to /var/lib/asterisk/... (also inside the file LCDial.sh).

Compiling it

What? It's a shell script...

Help

Feel free to holler at the author Enzo Michelangeli

See also



Asterisk | Asterisk cmd dial

LCDial.sh AGI script evolves into LCDC: the Least Cost Dialplan Compiler

Product End-of-Life Announcements

No new versions of LCDial.sh should be expected, as the product has now been superseded by the LCDC, the Least Cost Dialplan Compiler: much faster and more portable, as it allows to find the least cost route directly in the dialplan, without involving AGI. Try it, it's great!

Synopsis

AGI script, written for the shell interpreter ash, that performs an ASCII flat file lookup to find the cheapest Provider for a given destination number, and then invokes the Dial command, similarly to the Application LCDial (but without MySQL or any other database!). Also, an ENUM lookup is always automatically attempted before considering the actual providers (this requires the proper configuration of Asterisk's enum.conf).

Description

  • LCDial.sh(number_to_dial,timeout,options,URL,maxcost[,conffile][,announce.sh]) — dial one channel

Parameters:

  • number_to_dial specifies the number which should get dialed.
  • "timeout", "options" and "URL" are the same as within the standard Asterisk cmd dial command (they are directly passed to the dial comand).
  • "maxcost" is an optional value, expressed in millicents (thousandths of a cent), that puts a ceiling to the acceptable cost per minute for the call being initiated.
  • "conffile" is an otional "per-call" custom configuration file, replacing the default LCDial.sh.conf
  • "announce.sh" is an optional announcement script played just before attempting a "Dial()"

Return codes

Always returns 0, and with the ${DIALSTATUS} variable set by the last Dial internally executed (see Asterisk cmd dial).

Example:
exten => 4000,1,AGI(LCDial.sh,${EXTEN},15,,,14500)

...will ignore any route costing more than 14.5 cents per minute.

Installation, configuration and use

See this file.

NEW in version 1.1: Routes with the same cost are sorted based on the provider's position in the configuration file. This allows to enforce preferences, listing preferred providers before less desirable ones. Also, added to the package the "finareafreecoverage" script that prints, based on the information contained in the p_ and c_ files, the free routes comparative table shown at Finarea SA.

NEW in version 1.0: added optional parameter to specify the pathname of a shell script that will be run just before Dial(), typically to play an announcement of the call's cost. A sample /usr/lib/asterisk/agi-bin/announce.sh is included.

NEW in version 0.9: limited to free routes only, a MUCH faster alternative that does not use AGI is now available: see the doc file in the section describing how to use the utility "buildfreeroutes".
(Bugfix in version 0.8a: exended compatibility to old versions of ash that do not support "$((...))" arithmetic expansion; also, checkrates.cgi now works again.)

NEW in version 0.8: automated generation of ratefiles from provider description files (p_ files) and country files (c_files). Useful particularly for quickly updating the configuration to reflect the "free destinations" offered by some providers. NOTE: as "exclusion" rate, "9999999" must now be replaced by "!" (for all the details, see the doc file).

(BugFix in version 0.7a: replaced flaky open_r/close_r code with safer alternatives; gzip-compressed country.csv file used by checkrates.cgi; updated some rate files.)

NEW in version 0.7: possibility of specifying alternate configuration files on per-call basis; possibility to flag providers as "only providing routes more expensive than NNN millicents/minute", so to achieve a speed optimization when looking only for cheap or free routes (see doc file).
Also, a simple "Rate checker" web app written in Haserl (OpenWRT version available) to compare the rates to a given destination from the termination providers installed in LCDial.sh.conf . Of course, LCDial.sh will try them in reverse cost order.

(BugFix in version 0.6a: a missing "-n" option to sort caused incorrect results with GNU sort, although not with Busybox' sort. Many thanks to Marat Gulevich for spotting this!)

(BugFix in version 0.6: Now the script also works with bash as shell, not only with ash. Also, added rate table for VoipStunt.)

BugFix in version 0.5a: a few fixes to various ratefiles; Sixtel's removed altogether, due to their dismal service. Also, the gatherer scripts for VoipJet and Teliax now avoid unnecessary writes to flash memory if the respective rate files are found not to have changed. This means that you may safely invoke those gatherers more often.)

NEW in version 0.5: two ash scripts that can be started as cron jobs to build automatically updated rate files for Teliax and VoipJet (my preferred PSTN termination providers), after harvesting the necessary information from the .csv documents made available on the respective websites. (I would create one also for Voxee, if they did not make available only a silly Excel file, with several screwed-up entries to boot...).

(BugFix in version 0.4b: the format of the dial channel derived from ENUM lookup through dig was incorrect, and has been fixed. Also: a NOANSWER within 5 seconds of dialing and an ANSWER within 20 seconds are now treated as CHANUNAVAIL, and the next route is tried. Finally, fwdout has been added as (free) provider.)

(BugFix in version 0.4a: in /etc/asterisk/lcdialsh/LCDial.sh.conf , "voipbuster.com" was wrong, and has been corrected into "voipbuster" . In order to authenticate with the peer, Dial()'s parameters should always contain references to accounts defined in iax.conf or sip.conf, not to hosts.)

NEW in version 0.4: lines in the rate files may be commented out by '#' or ';' characters (actually, anything on the line after those characters will be ignored). ALSO, the lines in the configuration file may now specify an optional fourth field, a "number-to-postdial digits" rule, useful for dialing through FXO ports using call cards or cheap/free phone-to-phone IDD services (for instance, Finarea's HongKongCall.com or, in UK, DialWise.co.uk).

NEW in version 0.3: each line in the rate files may now optionally contain additional integer parameters representing start time, end time and weekdays of the interval when that rate applies (see docs).

NEW in version 0.2: if dig is installed, it is used to retrieve all the ENUM NAPTR records rather than only the first through Asterisk's EnumLookup (see docs).

Getting it

Here is an ipkg package for installation on embedded platforms such as OpenWRT; it may also be opened e.g. with "tar -zxf" or, under Windows, 7Zip and installed manually. It includes documentation, sample configuration file and a few sample rates files (please read the disclaimer in the README.txt).
Please note: on platforms other than OpenWRT, some paths are likely to be different: in particular, /usr/lib/asterisk/... will probably have to be changed to /var/lib/asterisk/... (also inside the file LCDial.sh).

Compiling it

What? It's a shell script...

Help

Feel free to holler at the author Enzo Michelangeli

See also



Asterisk | Asterisk cmd dial
Created by: enzo, Last modification: Thu 04 of Nov, 2010 (06:29 UTC) by admin
Please update this page with new information, just login and click on the "Edit" or "Discussion" tab. Get a free login here: Register Thanks! - Find us on Google+