LCR for FusionPBX Manual

This manual will guide you on every detail about how to install and use the LCR for FusionPBX native application.  If you want to have a quick setup, you may read the quick guide and later return here.

Content

Current version 1.4.0.

1. LCR for FusionPBX installation
2. LCR for FusionPBX configuration
3. Maintenance Tasks
4. Default Settings
5. LUA & FreeSWITCH Variables

Assumptions: The reader is familiar with Linux and FusionPBX.

LCR for FusionPBX Installation

Before you start LCR for FusionPBX installation, you must satisfy the next requirements:

• You need to have FusionPBX 4.4 or better installed with MySQL, MariaDB or PostgreSQL as database data storage.  If you don't know how to do this, OKay offers Linux consultant services.
• You need to have PHPShadow extension installed. If you are using OKay's RPMs you can type yum install php-shadow-loader. If you prefer the manual installation, you can go to https://phpshadow.com/download and follow the directions.
• You need to have SSH access and to be able to write in /app directory where FusionPBX is installed.
• You need to have access to FusionPBX as superadmin.
• You need to download and get an LCR for FusionPBX license.
• You must have installed the mod_lcr module (optional). The installation procedure depends on how you installed FreeSWITCH: source, DEB's, RPM's.

When you satisfy these requisites, please follow the next steps:

RPM Installation

This method only applies if you are using the RPM's from the OKay's repository.

1. Type yum install fusionpbx-lcr,
2. Go to Advanced->Upgrade menu, select Schema and Menu Defaults
   
3. Go to Advanced->Group Manager and review the LCR permissions, you should have it at least for the superadmin.
4. Log out and log in again into FusionPBX.
5. Go to your scripts directory, /usr/share/freeswitch/scripts and verify that app/lcr exists. If it doesn't, do the following: cd app && ln -s /var/www/html/fusionpbx/app/lcr/resources/install/scripts/app/lcr this will create a symbolic link.

Source Installation

1. Go to app directory where FusionPBX is installed, for example: cd /var/www/html/fusionpbx/app. If you are using the default FusionPBX installation script, it is very likely the path is /var/www/fusionpbx/app.
2. Copy LCR for FusionPBX in the server (by FTP or SCP), you can place it in /tmp directory
3. Inside the app/ directory, execute the command tar -jxvf /tmp/lcr-crypted.tar.bz2
4. If you are using LCR for FusionPBX older than 1.3.0, then depending on which database you use, copy lcr.conf.xml.mysql, lcr.conf.xml.mariadb104 or lcr.conf.xml.pgsql file into autoload_configs directory (for example: /etc/freeswitch/autoload_configs/) cp lcr.conf.xml.mysql /etc/freeswitch/autoload_configs/lcr.conf.xml. Edit lcr.conf.xml file and change the DSN values with yours. The DSN values can be taken from the file /etc/fusionpbx/config.lua.
5. Log into FusionPBX as superadmin and go to System->Modules menu, enable and start LCR module.
6. Go to Advanced->Upgrade menu, select Schema and Menu Defaults
   
7. Go to Advanced->Group Manager and review the LCR permissions, you should have it at least for the superadmin.
8. Logout and login again into FusionPBX
9. Go to your scripts directory, usually at /usr/share/freeswitch/scripts and verify that app/lcr exists. If it doesn't, do the following: cd app && ln -s /var/www/html/fusionpbx/app/lcr/resources/install/scripts/app/lcr this will create a symbolic link. Depending on the installation method, the route of your FusionPBX installation may vary.

License Installation

Go into / your LCR directory (usually /var/www/html/fusionpbx/app/lcr or the right directory where you installed) and execute echo -n key > any_name.key command, where the key is your license number. Since version 1.0.1 license name can have any name with .key extension. You don't need to do this if you hold an IP license; IP licenses can be obtained only if you make a donation to convert the project into open-source.

LCR for FusionPBX Configuration

To configure LCR for FusionPBX, you need to understand the next concepts:

Carrier

A Carrier is a company that provides VoIP services. For example To Call Me or To Connect Me.

Gateway

A Gateway is a SIP access definition (server, port, user, password, etc). They can be configured by going to the Accounts->Gateways menu option. A Carrier can have zero or more linked Gateways.

Channel

A Channel shows how many simultaneous communications a Carrier can do. This value is only useful to control outgoing calls.

Codecs

The Codecs are set in a string (comma separated), they define the type of codec a Carrier has. Not all Carriers have the same codecs. If this string is empty, FusionPBX will send the default value set in System->Variables menu.

Suffix

A Suffix adds a string before sending the dialstring to Carrier. Some Carriers need a suffix to give you service.

Rate

A Rate defines how much does it cost to connect to a destination if the digits match.

Carrier Configuration

1. Add all the needed Gateways. Go to Accounts->Gateways menu. Technical information for each Gateway must be acquired from your Carrier.
2. Go to Apps->LCR menu and add a Carrier.
   
   Carrier's name must NOT have spaces. The channel number must be a positive integer if you don't know this value uses a safe value. Select true for Enable field. Save the Carrier.
   New versions of LCR introduce the priority. This value is used in order to ignore pricing and give priority to some carriers. All carriers with the same priority will be ordered by the rate of the destination. Put 0 to get the maximum priority. Use a safe value (5) in all your carriers if you don't plan to use this feature.
3. Go to Accounts->Gateways and add the gateways for your given carrier. Contact your technical support to get the technical information.
4. Edit the new Carrier, you will see you can add new information.
5. If your Carrier is for outgoing calls, link the Carrier.
   
   Select the Gateway (prefix) you want to link. If your vendor needs a suffix, you can configure it here. Specify the Codec string, for example, 729, GSM, PCMU; you can leave this parameter blank, the system will use codecs from FusionPBX. Select true to Enable field.
   The new LCR introduces the priority by the gateway as well. Since a carrier may have more than one gateway, this feature is very handy if you want to give priority to a specific gateway because of the geographic location. If you don't plan to use this feature, you can put a safe value in all your gateways. The value doesn't matter as far as they are all the same.
6. Add a rate. You will see later how to upload a CSV file.
   
   
   Specify which digit will identify this rate (rates are selected using the closest match if you are dialling 1 613 800 7370 a 1613 prefix will hit instead of a 1 prefix). Select if this rate will be for incoming, internal (for extension to extension, or from extension to an internal component, such as a conference hall) or outgoing call. Tell this rate cost and currency. Some vendors give a different rate for connection, if you don't know this data, you may let all "rate" fields with the same value. If you are using the original lcr.conf.xml file from LCR for FusionPBX, the LCR Profile value must be "default"; LCR Profile is used to allow different rating lists.
   The new versions of the LCR support now NADP (aka intra-lata, intra-state). If your carrier gives you those rates, you can put them here.
   Since LCR 1.3.x, there is also a way to input origination rates. Origination rates are used to give special rates to a given destination rate depending on who is calling. For example, you can give a cheaper rate when someone calls Canada if the caller ID number comes from North America.
7. You can add rates using a CSV file. The file must have the next fields:
   Destination, Prefix, Connect Increment, Talking Increment, Rate, Currency, Connect Rate, Direction(inbound, outbound, internal), Start Date, End Date, Profile, Random (any value you want). The easiest way to obtain the CSV file is just by adding one rate and exporting it.

Repeat steps 2 to 7 for each Carrier you need to add.

Finally, if you want to use mod_lcr approach: you need to change routes to allow them to use LCR for FusionPBX. Go to Dialplan -> Outbound Routes menu and change dialplans from bridge sofia/gateway/... to bridge lcr/default/... Please read Freeswitch documentation if you are not familiar with dialplan syntax.

The configuration file has the nobill profile, that will route without billing. When you are done uploading all your rates, change your bridging statement to lcr/nobill/XXXXXXXX. Usually, lcr/nobill/$1, however, it depends on your dialplan.

LUA LCR Replacement 

If you want to use the LCR LUA replacement (recommended), change the bridge statements to Lua statements. lua app.lua lcr $1 where $1 will have the number to route to.

Edit or create the /etc/fusionpbx/local.lua script with the following content:

debug.lcr = true;
expire.lcr = "3600";
lcr = {};
lcr.diversion = false;
lcr.anti_cancel_caller_id_number = true;
lcr.anti_cancel_callee_id_number = true;
lcr.anti_cancel_accountcode = false;
lcr.nanp = true;
lcr.anti_cancel_evaluation_period = 30;

To understand more, please read the LUA & FreeSWITCH Variables section.

Maintenance Tasks

Updating the Rates

Updating the rates is maybe one of the most complex and longest tasks. The easiest way to do this is to download the rate list, modify it and upload it again (check the clear ALL rates before importing field).

The easiest way to obtain a valid CSV file is by entering one rate and then click on the download button. It will download a CSV. Some notes about the CSV:

• The decimal point is a point, some software may change it to a comma because of the language settings
• Alphanumeric values (different than numeric) must be enclosed by double quotes (") always.

Updating from To Connect Me

To connect me is the Termination Trunk service from OKay Inc. You can update the rates automatically by following these steps:

1. Get your Billing Profile UUID number from To Connect Me. This can be done by logging into https://trunks.okay.network and going to Apps->Billing. You will find your To Connect Me billing UUID there.
2. Get the local UUID in your LCR. After adding a carrier to host the To Connect Me trunk, edit it. And extract the UUID from there.
   
3. Add the following default settings:
   

   Category	Sub Category	Type	Value
   lcr	to_call_me_carrier_uuid	text	UUID from step 2
   lcr	to_call_me_uuid	text	UUID from step 1

4. Go to the command line and go to your FusionPBX base directory (usually /var/www/html/fusionpbx if you use OKay's RPMs or /var/www/fusionpbx if you use the generic installation script) and execute php app/lcr/lcr_import_to_connect_me.php . You can add the following flags:
   • -d: turn on the debug
   • -p: prefix to import. Recommended. Please use it as if you don't, your server will pull all the rates at once (more than 100k lines) and your server may not have enough resources to hold a big array in the memory. The best approach is to create some crontabs with specific prefixes.
   
   for example php app/lcr/lcr_import_to_connect_me.php -p 1514 to pull Montreal rates.

LCR for FusionPBX update

You may follow the installation procedure for any update. In short, do the following:

1. Replace the files
2. Run the Upgrade script
3. Enable the new permissions

Default Settings

 The following default settings are used in the LCR for FusionPBX software.

LUA and FreeSWITCH Variables

The following table explains the parameters.

If you specify a FreeSWITCH variable, the variable will have precedence and the Lua value will be overridden.