Archives

extMOHSetter

Click here for the code.


When setting custom music on hold (MOH), you’ll likely encounter that the extension will only use the ‘default’ MOH class with no way to alter this via the FreePBX GUI. More specifically, on outbound calls or extension to extension calling/transfers, the default on-hold music is played instead of the custom MOH. Furthermore you can only set up the custom MOH on inbound routes, ring groups, call queues, or conferences.

There is a setting that can be set via the CLI in one of the asterisk configuration files which does allow for custom or alternate MOH classes to be associated with certain/all extensions. We’ve therefore written a CLI tool that helps automate this alteration. The tool is called from the CLI with this command: extMOHSetter i.e.:

 [root@pbx /]# extMOHSetter /tmp/extensionList.txt MOHClassName 

It uses a simple extension list as the first parameter ( extensionList.txt in the above example), and the second parameter is the MOH Class name which is set via the FreePBX Music On Hold Module.

checkBlf Tool

Click here for the code.


checkBlf is a new tool added to the PPT server. It simplifies the searching for in-use BLF files in order to expedite the updating of sidecars. The is especially useful for companies that have many blf files to search through.

The use of the tool is rather simple. Once on the PPT server, change into the directory for the customer you are currently working on. You will then call the checkBlf command and it will check through all the BLF files and the MAC configuration files to find those BLF files in use. It will only show you output for the files currently in use.

Here is an example use:

[root@ppt / ]# cd /home/1900027
[r[root@ppt /home/1900027 ]# checkBlf 
[blf-cdc.cfg]
0004f2ab8765.cfg
 
[blf.cfg]
0004f25f1180.cfg
0004f28226bb.cfg
 
[blf-testing.cfg]
0004f28099ab.cfg
 
[root@ppt /home/1900027 ]# 

So in this case we can see that blf-cdc.cfg is being used by 0004f2ab8765.cfg, blf.cfg is being used by both 0004f25f1180.cfg and 0004f28226bb.cfg, and blf-testing.cfg is used by 0004f28099ab.cfg.

Workflow for BLF Updates

This document covers the workflow for updating the BLF configuration for clients with shared Google Docs spreadsheets.

  • Begin by opening the Google Docs spreadsheet containing the updated BLF information. Click somewhere within the spreadsheet, select all using Ctrl+A, and then copy the information using Ctrl+C.
  • Open a terminal and access the Papal Mainframe via ssh, select the PPT server, enter container 100 using sudo vzctl enter 100 and enter the home directory of the CTID whose BLF configuration you wish to update.
  • Create a new file for the BLF information. Please name the file with an appropriate description followed by an ISO standard formatted date (yyyymmdd) in order to promote consistency and prevent confusion. For example:
nano blfsidecar-20160114
  • Paste the BLF information from the Google Docs spreadsheet into the newly created file using Ctrl+Shift+V, save the file using Ctrl+O, and exit the file using Ctrl+X.

Note: A direct copy and paste from a Google Docs spreadsheet will not yield properly formatted CSV data. This won’t matter here, but may be a concern for other uses.

  • Using the makeblf command, generate a new BLF configuration file from the file you just created. For example:
makeblf blfsidecar-20160114 file
  • You will now have a properly formatted BLF configuration file with the name you specified above and the .cfg extension. Using our above example, the file would be named blfsidecar-20160114.cfg.
  • At this point you can now specify the new BLF configuration file inside individual phone configuration files. If your new BLF file is intended to replace an existing BLF file within several phone configuration files, you can use the sed command to change them all at once. Example usage follows. Do note the *cfg as the target, otherwise you may overwrite log files as well.
sed -i -e ’s/oldfile.cfg/blfsidecar-20160114.cfg/g’ *cfg
  • Congratulations, you may now have the customer reboot or reload the configuration on the affected phones.

makeblf

makeblf is a tool on the PPT server for automatically generating properly formatted BLF configuration files from CSV data and/or data copied/pasted from customer BLF spreadsheets located in Google Drive. makeblf is not meant to serve as a replacement for in-place editing of BLF files for minor changes, rather its purpose is to create new BLF files when necessary.

To run makeblf, use two arguments: the first being the file name where the input data is stored, the second being either text or file depending on which format you would like the output data. An example use might be:

makeblf inputfile.csv text

This would take the data stored in inputfile.csv, format it for use as a BLF configuration file, and output it as text to the terminal. Another example use might be:

makeblf inputfile.csv file

This would take the data stored in inputfile.csv, format it for use as a BLF configuration file, and write it to a file named inputfile.cfg, which could then be specified in any given phone’s configuration.

For additional information on proper makeblf workflow, please see the article titled Workflow for BLF Updates.

makeppt

Click here for the code


makeppt is a tool on the PPT server that creates a new PPT user and directory. Under normal circumstances this should only be necessary while onboarding a new customer, but there are occasionally exceptions. In total, the tool performs the following actions in the following order:

  1. Create the home directory for the new user by copying a template directory
  2. Add the new user
  3. Set the new user password.
  4. Adjust permissions on the home directory for the new user
  5. Create the web interface directory by copying a template directory
  6. Edit the configuration in the new web interface directory to reflect the new user

An example use of makeppt is as follows:

makeppt 1900027

If the tool is successful, it will output the following information:

adduser: warning: the home directory already exists.
Not copying any file from skel directory into it.
Success!

Otherwise the tool will output a nondescript error message. Be warned that because of the size of the template for the user’s home directory, running makeppt can take a couple of minutes to complete.

rf-sbc-repair

Click here for the code.


Configuration files for any given phone within a CTID home folder on the PPT server need to reflect the correct outbound proxy address in order for that phone to successfully register with the PBX. Automatic configuration file generation via the tool at p.ringfree.biz does not set this value. The value may be set by manually editing the relevant configuration files or by using the rf-sbc-repair tool.

The rf-sbc-repair tool parses the CTID home folder for all instances of the reg.1.outboundProxy.address within the configuration files that have an empty value. It then calls a sed command to replace the empty value with the correct value of sbc001.ringfree.biz. It does attempt to identify and skip template files during this process. Finally it runs the rf-ppt-repair script to repair permissions and ownership of all files within the directory.

To use rf-sbc-repair, simply run it with the target CTID as the only argument:

rf-sbc-repair 1900027

It will output details regarding any files it edits and any template files it skips. Because it runs rf-ppt-repair within it, there is no need to run it separately before or after.

rf-ppt-repair

Click here for the code.


Provisioning and configuration files on the PPT server within the various CTID home folders need to be owned by their respective users and have universal read/write/execute permissions. Files automatically generated meet neither of these criteria and manually changing permissions and ownership is tedious and time consuming , especially if there are large numbers of files.

The script rf-ppt-repair was written to streamline the process of adjusting permissions and ownership in this particular use case. The script is run with a CTID passed as an argument:

rf-ppt-repair 1900027

It then applies the requisite ownership and permissions to everything within that CTID home folder.

getmac

Click here for the code.


getmac is a tool on the PPT server that returns the MAC address of each phone associated with a given extension along with some additional information. It’s useful when an end user is able to provide an extension but not a MAC address for whatever reason. In most circumstances getmac will return a single result, however, in PPT folders where phones are moved between extensions frequently, multiple results will be returned. getmac parses the current working directory and will return an ls warning if used elsewhere.

An example use case would be trying to find the MAC address for the phone associated with extension 104 within /home/1900027:

getmac 104

This will return the following results:

-rwxrwxrwx 1 1900027 1900027 1611 Apr 19 2013 0004f2476c65.cfg
-rwxrwxrwx 1 1900027 1900027 1672 Feb 9 15:48 0004f28099ab.cfg
-rwxrwxrwx 1 1900027 1900027 1655 Jul 22 2015 0004f28c07e4.cfg

In this case we see three MAC addresses that have been associated with extension 104. The MAC address 0004f28099ab was edited most recently thus we can safely deduce that it is the MAC for the phone presently associated with the extension.

Again in most cases getmac will return a single result, thus eliminating the need to compare timestamps. The decision was made not to only have it return the most recent MAC address as returning all of them could prove useful in some circumstances.

Inbound Route Import Tool

Click here for the code.

Click here for a sample import.


 

The Inbound Route Import Tool, or irimport is a command line program for bulk importing inbound route and/or DID information from a properly formatted CSV file. The program takes a single argument: the CSV file to be imported, and ignores all other arguments passed to it. The program will verify that the specified file exists and will exit with an error status if does not. Attempting to use the program with no arguments will simply display usage information and the program will exit normally.

An example use of the program is:

irimport example.csv

It is imperitive that the CSV file specified when running the program is formatted in such a way that the program can use it. The required format uses four columns: DID, Description, Destination Type, and Destination ID. The file should have one row per inbound route to be imported. Information in columns beyond the fourth will be ignored by the program.

An example CSV file might be:

18281234567,Main,ivr,3
18282345678,Support,timecondition,1
18283456789,Sales,ringgroup,600
18284567890,Unused,terminate,hangup
18285678901,Direct,extension,101

In each line of the above example, the first column contains the DID to be used with the inbound route. For each DID, please enter an eleven digit unsigned integer in order to avoid errors.

Following the DID is the Description of the inbound route. For each Description, please use an alphanumeric string. Spaces may be used, but please avoid punctuation and other symbols.

Following the Description is the Destination Type. At present the program support five Destination Types:

terminate
extension
ivr
timecondition
ringgroup

Please use one of the five stated values. Use of other values will result in an error and an unsuccessful import of the DID. Note that this will not cause the program to exit. I’ve taken the above example CSV file and edited it slightly:

18281234567,Main,ivr,3
18282345678,Support,timecondition,1
18283456789,Sales,ringgroup,600
18284567890,Unused,example,hangup
18285678901,Direct,extension,101

Note that on the fourth line, I’ve replaced terminate with example. Now when the program runs using that CSV file as the argument, the following output is displayed:

18281234567 imported successfully.
18282345678 imported successfully.
18283456789 imported successfully.
Error: 18284567890 NOT imported successfully.
18285678901 imported successfully.

Finally, following the Description Type is the Description ID. Acceptable values for the Description ID depend on the Description Type.

Acceptable values for the ivr and timecondition types are unsigned integers which correspond with the ID of the IVR or Time Condition. To obtain this value, you may copy the link address of the IVR or Time Conidition from within the pbxadmin interface. The ID will be at the end of the string.

Acceptable values for the extension and ringgroup types are unsigned integers which correspond with the Extension Number or Ring Group Number. These values can easily be obtained from within the pbxadmin interface and their locations should be obvious to anyone familiar with the interface.

Acceptable values for the terminate type are as follows:

hangup
congestion
busy
zapateller
musiconhold
ring

The values correspond with the available options within the pbxadmin interface.

Extension Import Tool

Click here for the code.

Click here for a sample import.

Click here to download the application.


The Extension Import Tool, or extimport is a command line program for bulk importing user extensions into a PBX from a properly formatted CSV file. The program takes a single argument: the CSV file to be imported, and ignores all other arguments passed to it. The program will verify that the specified file exists and will exit with an error status if does not. Attempting to use the program with no arguments will simply display usage information and the program will exit normally.

An example use of the program is:

extimport example.csv

It is imperitive that the CSV file specified when running the program is formatted in such a way that the program can use it. The required format uses twelve columns: Type, Extension, Description, Caller ID Number, Enable Voicemail, Voicemail Password, Voicemail Email, SIP Secret, Enable Follow Me, Follow Me Number, Emergency Caller ID Number, and Follow Me Ring Time. The file should have one row per extension to be imported. Information in columns beyond the twelfth will be ignored by the program. Several of the fields will accept blank values, the specifics of which will be outlined below.

An example CSV file might be:

sip,100,Joe,18285555555,1,100,joe@joe.com,password,1,,,20
virtual,200,Jim,18287777777,1,200,,,1,18288888888,,60
sip,101,Sal,18289999999,1,101,,secret,,,18280000000,
sip,102,Amy,,,,,longpassword,,,,
sip,103,Jan,18282222222,1,103,jan@jan.com,password,1,,,
virtual,201,Bob,18283333333,1,201,,,1,18284444444,,

Type

This determines whether the line contains information for a SIP extension or a Virtual extension. This field will accept any value. Using the value sip will tell the program to use a SIP extension while any other value will tell the program to use a Virtual extension.

Extension

This determines the extension number that will be assigned to the extension being imported. Acceptable values are three or more digit unsigned integers excluding three digit values beginning with the number nine. For example 922 would not be an acceptable value.

Description

This determines a non-numerical means of identifying the extension. This field takes a string as a value. In most cases the first and last name of the person assigned to the extension are used, however generic descriptions are also acceptable.

Caller ID Number

This determines the outbound caller ID number to be used with this extension. You may optionally leave this field blank if you would prefer to use the system default outbound caller ID. Acceptable values are eleven digit unsigned integers.

Enable Voicemail

This determines whether voicemail will be enabled for the extension. To enable voicemail, please use a value of 1 in this field. To not enable voicemail, please leave this field blank.

Voicemail Password

This determines the default password for the voicemail box associated with the extension. Acceptable values are three or more digit unsigned integers. Please use a value for this field if voicemail will be enabled for the extension, otherwise please leave this field blank.

Voicemail Email

This determines whether or not the email attachment voicemail feature is turned on, and if so to which email address it should send the attachment. Acceptable values are valid email addresses. You may optionally leave this field blank to turn off the email attachment feature. If voicemail will not be enabled for the extension, please leave this field blank.

SIP Secret

This determines the SIP secret or password associated with the extension. This field accepts a string. The value of this field is ignored when importing virtual extensions. A value is required in this field when importing SIP extensions. Be careful to avoid the use of commas in this value as they could cause errors while running the program.

Enable Follow Me

This determines whether the Follow Me feature is enabled for the extension. To enable the Follow Me feature, please use a value of 1 in this field. To not enable the Follow Me feature, please leave this field blank.

Follow Me Number

This determines a single optional additional phone number to add into the Follow Me settings. Acceptable values are eleven digit unsigned integers. If you do not intend to add a number here, please leave this field blank.

Emergency Caller ID Number

This determines the outbound caller ID number to be used when the extension makes an outbound phone call to an emergency line such as 911. Acceptable values are eleven digit unsigned integers. While not technically required, best practise is to always use a value here when importing SIP extensions. Values in this field are ignored when importing Virtual extensions.

Follow Me Ring Time

This determines the Ring Time as specified in the Follow Me settings for the extension. Acceptable values are unsigned integers beginning at 1 and ending at 60. The default value is 20. If left blank, the default value will be used.

Notes on running the Extension Import Tool

  • On a successful import, the Extension Import Tool will display no output
  • Best practise is to place the Extension Import Tool at /usr/local/bin/extimport
  • Best practise is to place CSV files to be imported in /root or /tmp