At the start of this process I decided to use the Centos ISO for installing FusionPBX. Well, I'm beginning to question this decision now for the following reasons:
1. although I can update the FusionPBX code very easily with a single button to press, I cannot update the Freeswitch version without learning how to compile updates from git. This is because there are no updates available for FusionPBX using a package manager in Centos at this time.
2. There are permission issues in the Centos image - as you will have already seen earlier in my blog - I've fixed some of them but I suspect that there are others as there are still some things that don't work right.
3. It seems that Centos is not the most efficient OS and takes more memory to function well than something like FreeBSD does.
So I'm looking to change to FreeBSD. Actually to be more precise, I'm looking to change to pfsense because this runs on FreeBSD and actually uses an even more stripped down version of FreeBSD so that it runs with less memory. Doing this apparently solves all the problems I've identified above. I'm going to start by trying pfsense 1.2.3 not pfsense 2 as I understand it isn't quite working well with version 2 yet.
UPDATE: Well, I've installed pfsense a few days back (using the download here: http://www.pfsense.org/index.php?option=com_content&task=view&id=58&Itemid=46) and loaded fusionpbx on top of it (using these instructions: http://wiki.fusionpbx.com/index.php/PfSense_Install#pfSense_1.2.3_or_pfSense_2.0). I'm still fiddling with the setup a little and experimenting with it and when I'm happy I'll post more details. For now the update is that it seems to be good, although I think I may have a permission problem right now that I need to overcome and document. One of the nice benefits that there seems to be is that pfsense appears to come already setup with OpenVPN which means that once I have that up and running remote administration should be very straightforward in theory, though I haven't tried it yet.
Warning: I have been informed that there is a problem running fusionpbx on an embedded version of pfsense - apparently due to the file system used by pfsense, some data is lost when the machine is rebooted and this impacts the operation of fusionpbx. This issue apparently does not apply to pfsense installed on a harddrive though.
My conclusions may not suit you. You need to work out what is important to you and to test it yourself!
Monday, August 23
Wednesday, August 11
Faxing
FusionPBX faxing has a lot of promise. From all accounts it appears that when the function works it works much more reliably than Asterisk based faxing.
Something I learnt is that if you select ADVANCED, XML Editor a new window will open. Choose autoload_configs from the list, then choose fax.conf.xml
In fax.conf.xml there is an option that by default sets a variable called verbose = false. If you change this to true you get more logging details as the fax is actually received, such as the quality of the connection etc. You can see these details when you run the freeswitch command line ie. /usr/local/freeswitch/bin/fs_cli
Well there are lots of things that can go wrong. So others can learn from them here goes:
- careful that the extension you use for your fax is not valid for something else! In my case I used 8001. This turned out to be valid for the feature code that changes group membership or something (see dial plan, advanced). For information on how to diagnose a fault like this see my blog entry on dial plans.
- I changed the fax extension from 8001 to 7701 and this got me closer. Now I appeared to have a permission problem. But in reality, because I had changed the number rather than creating a new fax extension from scratch, it created the folder for 7701 but failed to create the "inbox" and "sent" folders underneath that, and so when the fax server tried to write to the inbox folder it had an error. If I'd created the fax extension from scratch I wouldn't have had this problem.
- in the process of doing all this, I have made an enhancement to the fax processing script that has now been incorporated into the official release of FusionPBX (for more details see below). My enhancement tells you any error message from the fax receipt process (if you fail to successfully receive a fax you receive an email but the email contains no attachment - this addition allows you to know why you didn't get an attachment), the fax senders' identification information, and the number of pages in the fax (not necessarily the number of pages received).
Limitations of the fax server functionality: With the fax server in its current form it is not possible to send a fax to the fax server from an extension on the same phone system. I was doing my testing using a fax machine connected to an ATA on an extension of the phone system and the system fails to send the fax as an email because when the fax machine hangs up, the call terminates and the fax_to_email script is never executed. The only way to make this work is to modify the dialplan created by the fax server function so that prior to starting rxfax it sets the variable api_hangup_hook=system /usr/bin/php /var/www/fusionpbx/secure/fax_to_email.php email=youremailaddress@yourdomain extension=yourfaxextension name=${last_fax}
(where the bit following the keyword of system is the exact same data that is automatically put into the dialplan of the fax configuration on the action system line that follows the line containing rxfax). This limitation does not apply to externally sent faxes and therefore this line is not necessary. Accordingly unless you have a really good reason to change it so you can receive internal faxes I think you should stick with the standard fax server configuration.
My Enhancement of the fax server functionality (this is now included in FusionPBX)
The enhancements I have implemented are:
- create a log of sent faxes - because I was frustrated in the debugging process of the fax to email script that although I could tell that freeswitch had received the fax I was unable to tell if the fax had ever been attempted to be emailed because FusionPBX doesn't use an MTA (message transfer agent eg. sendmail) to send the messages and therefore there is no message queue to check. The log is /usr/local/freeswitch/storage/fax/emailed_faxes.log
- add sending retries on failed email - I discovered that if the email server is misconfigured, or uncontactable at the time the fax is received, then the fax_to_email process fails and the user never receives the fax - it is just stored on the server. So I added a section to the script that enables it to queue messages it cannot send when the email server is not contactable. It will continue to retry sending these messages once every 3 minutes. The messages will queue on the server until sending is successful. These messages are queued in /usr/local/freeswitch/storage/fax/failed_fax_emails.log - the lines in that file are actually executed by the re-sending process, so the structure of the lines is important.
- added checking to see if there is an attachment on the server to send. If there isn't one it will send an appropriate message in the fax email. This is helpful when we have a failed fax, it is also helpful if someone manually deletes queued faxes before we successfully email them.
Something I learnt is that if you select ADVANCED, XML Editor a new window will open. Choose autoload_configs from the list, then choose fax.conf.xml
In fax.conf.xml there is an option that by default sets a variable called verbose = false. If you change this to true you get more logging details as the fax is actually received, such as the quality of the connection etc. You can see these details when you run the freeswitch command line ie. /usr/local/freeswitch/bin/fs_cli
Well there are lots of things that can go wrong. So others can learn from them here goes:
- careful that the extension you use for your fax is not valid for something else! In my case I used 8001. This turned out to be valid for the feature code that changes group membership or something (see dial plan, advanced). For information on how to diagnose a fault like this see my blog entry on dial plans.
- I changed the fax extension from 8001 to 7701 and this got me closer. Now I appeared to have a permission problem. But in reality, because I had changed the number rather than creating a new fax extension from scratch, it created the folder for 7701 but failed to create the "inbox" and "sent" folders underneath that, and so when the fax server tried to write to the inbox folder it had an error. If I'd created the fax extension from scratch I wouldn't have had this problem.
- in the process of doing all this, I have made an enhancement to the fax processing script that has now been incorporated into the official release of FusionPBX (for more details see below). My enhancement tells you any error message from the fax receipt process (if you fail to successfully receive a fax you receive an email but the email contains no attachment - this addition allows you to know why you didn't get an attachment), the fax senders' identification information, and the number of pages in the fax (not necessarily the number of pages received).
Limitations of the fax server functionality: With the fax server in its current form it is not possible to send a fax to the fax server from an extension on the same phone system. I was doing my testing using a fax machine connected to an ATA on an extension of the phone system and the system fails to send the fax as an email because when the fax machine hangs up, the call terminates and the fax_to_email script is never executed. The only way to make this work is to modify the dialplan created by the fax server function so that prior to starting rxfax it sets the variable api_hangup_hook=system /usr/bin/php /var/www/fusionpbx/secure/fax_to_email.php email=youremailaddress@yourdomain extension=yourfaxextension name=${last_fax}
(where the bit following the keyword of system is the exact same data that is automatically put into the dialplan of the fax configuration on the action system line that follows the line containing rxfax). This limitation does not apply to externally sent faxes and therefore this line is not necessary. Accordingly unless you have a really good reason to change it so you can receive internal faxes I think you should stick with the standard fax server configuration.
My Enhancement of the fax server functionality (this is now included in FusionPBX)
The enhancements I have implemented are:
- add fax status information into the email that is sent - the driving force for this requirement was that I discovered that a failed fax transmission (eg. a telephone calling the fax number rather than a fax) would result in an email that is sent without any fax attachment and without any explanation. Therefore I modified the script so that we could include messages as well. Additionally the action system line in the dialplan needs to change to support this as well: /usr/bin/php /var/www/fusionpbx/secure/fax_to_email.php email=youremailaddress@yourdomain extension=yourfaxextension name=${last_fax} messages='result: ${fax_result_text} sender:${fax_remote_station_id} pages:${fax_document_total_pages}'
(note that you can test faxing from your server by running this line interactively, but you can simplify it a bit as the variables mean nothing if you run it from the shell prompt eg. /usr/bin/php /var/www/fusionpbx/secure/fax_to_email.php email=youremailaddress@yourdomain extension=yourfaxextension name=the_name_of_the_fax_tif_file_without_a_file_extension messages='you don't need to put anything here')
(note that you can test faxing from your server by running this line interactively, but you can simplify it a bit as the variables mean nothing if you run it from the shell prompt eg. /usr/bin/php /var/www/fusionpbx/secure/fax_to_email.php email=youremailaddress@yourdomain extension=yourfaxextension name=the_name_of_the_fax_tif_file_without_a_file_extension messages='you don't need to put anything here')
- create a log of sent faxes - because I was frustrated in the debugging process of the fax to email script that although I could tell that freeswitch had received the fax I was unable to tell if the fax had ever been attempted to be emailed because FusionPBX doesn't use an MTA (message transfer agent eg. sendmail) to send the messages and therefore there is no message queue to check. The log is /usr/local/freeswitch/storage/fax/emailed_faxes.log
- add sending retries on failed email - I discovered that if the email server is misconfigured, or uncontactable at the time the fax is received, then the fax_to_email process fails and the user never receives the fax - it is just stored on the server. So I added a section to the script that enables it to queue messages it cannot send when the email server is not contactable. It will continue to retry sending these messages once every 3 minutes. The messages will queue on the server until sending is successful. These messages are queued in /usr/local/freeswitch/storage/fax/failed_fax_emails.log - the lines in that file are actually executed by the re-sending process, so the structure of the lines is important.
- added checking to see if there is an attachment on the server to send. If there isn't one it will send an appropriate message in the fax email. This is helpful when we have a failed fax, it is also helpful if someone manually deletes queued faxes before we successfully email them.
I hope this makes faxing simpler for you.
Thursday, August 5
Anyone hungry? How about Pizza?
When you load up FusionPBX you will notice that the dial plan contains an entry called pizza_demo. If you dial this using 74992 (ie. PIZZA) you will find that nothing happens! So what is it?
FreeSwitch includes a speech recognition demonstration called Gino's Pizza or "pizza demo". This is a great thing to have working on your system if you want to explore speech recognition technology (and for Trixbox users this is a big leap forward in capabilities). My initial thoughts after trying it is that you really need more confirmations along the way in your scripting because it is very easy to select a pizza topping you didn't actually want and then all you can do is go back to the beginning again if you get it wrong - but that is just scripting. The other thought I had was that there is a lot of silence after you say something, it would be good if the system acknowledged your response while it was working out what you said rather than just going away and thinking about it - it doesn't feel fluent yet. But that said, it is a great advance beyond DTMF IVRs.
So how do you get it running? Well actually, all that has been included in the ISO is the dialplan entry, everything else needed for it is missing due to space limitations in the ISO. So to get started we need to log in to the console. If you use putty you can cut and paste these steps.
cd /usr/local/freeswitch/scripts
wget http://svn.freeswitch.org/svn/freeswitch/trunk/scripts/javascript/ps_pizza.js
nano ps_pizza.js
edit the line in section Set audio params to say asr.setAudioBase("pizza/");
save the changes
mkdir js_modules
cd js_modules
wget http://svn.freeswitch.org/svn/freeswitch/trunk/scripts/javascript/js_modules/SpeechTools.jm
cd ..
chown apache -R *
chgrp apache -R *
cd ..
cd sounds/en/us/callie
wget http://www.freeswitch.org/eg/pizza_sounds.tar.gz
gzip -d *.gz
tar -xf *.tar
rm *.tar
chgrp freeswitch -R pizza
chown freeswitch -R pizza
cd /usr/local/freeswitch/grammar
wget http://www.bkw.org/pizza_gram.tar.gz
tar xvzf pizza_gram.tar.gz
watch for console messages when you call extension 74992 (pizza) to test it! To show the console run the following command.
FreeSwitch includes a speech recognition demonstration called Gino's Pizza or "pizza demo". This is a great thing to have working on your system if you want to explore speech recognition technology (and for Trixbox users this is a big leap forward in capabilities). My initial thoughts after trying it is that you really need more confirmations along the way in your scripting because it is very easy to select a pizza topping you didn't actually want and then all you can do is go back to the beginning again if you get it wrong - but that is just scripting. The other thought I had was that there is a lot of silence after you say something, it would be good if the system acknowledged your response while it was working out what you said rather than just going away and thinking about it - it doesn't feel fluent yet. But that said, it is a great advance beyond DTMF IVRs.
So how do you get it running? Well actually, all that has been included in the ISO is the dialplan entry, everything else needed for it is missing due to space limitations in the ISO. So to get started we need to log in to the console. If you use putty you can cut and paste these steps.
cd /usr/local/freeswitch/scripts
wget http://svn.freeswitch.org/svn/freeswitch/trunk/scripts/javascript/ps_pizza.js
nano ps_pizza.js
edit the line in section Set audio params to say asr.setAudioBase("pizza/");
save the changes
mkdir js_modules
cd js_modules
wget http://svn.freeswitch.org/svn/freeswitch/trunk/scripts/javascript/js_modules/SpeechTools.jm
cd ..
chown apache -R *
chgrp apache -R *
cd ..
cd sounds/en/us/callie
wget http://www.freeswitch.org/eg/pizza_sounds.tar.gz
gzip -d *.gz
tar -xf *.tar
rm *.tar
chgrp freeswitch -R pizza
chown freeswitch -R pizza
cd /usr/local/freeswitch/grammar
wget http://www.bkw.org/pizza_gram.tar.gz
tar xvzf pizza_gram.tar.gz
watch for console messages when you call extension 74992 (pizza) to test it! To show the console run the following command.
/usr/local/freeswitch/bin/fs_cli
To exit the console type ... (yes, three fullstops or if you are American, three periods) and then press Enter.
Enjoy your pizza! (oh, just remember, if you want to order real pizza you should call your local pizza shop - FusionPBX is good but it isn't actually going to cook and deliver your pizza for you)
Dial plans - CLI is your friend
Dial plans are complicated to understand. How can we see why things are failing to work the way we think they should?
CLI, the command line interface, is one of the most useful tools when it comes to understanding what is going on in your system. Here you can look in real time at what is happening when you try to make or receive a call and you can diagnose faults. I have to say that this has been the most useful piece of information when it comes to diagnosing issues with the dial plan (apart from learning to write regular expressions). To run the cli you type /usr/local/freeswitch/bin/fs_cli at the linux prompt. If you don't want to look real time you can also look at the logs in /usr/local/freeswitch/log/freeswitch.log. Note that if you are using the console of your server then you really need to be looking at the log as that way you'll be able to scroll back and forward using your text file viewer and see what you need to see. But if you use PUTTY you can use the cli as you'll be able to scroll back and forward using the scroll bar on the side of the putty window. Note that the putty line buffer is set to 200 lines by default - I tend to increase this to 2000 so that I have enough history to scroll back through.
When you are using the CLI you can exit the CLI back to the linux prompt by typing ... (yes, three fullstops in a row, or for Americans, 3 periods in a row). To diagnose dial plan faults, start the CLI and then dial the number you want to test using your phone. You will see a bunch of stuff flying past. You'll then hear your call failure (if you didn't have a call failure you wouldn't be diagnosing it would you...) and at that point press CTRL-S to freeze the CLI output until you are finished looking at it.
So you're looking at the log. Look for a line like this one:
2010-08-12 09:20:21.736881 [INFO] mod_dialplan_xml.c:331 Processing [THE NAME OF YOUR PHONE EXTENSION YOU DIALED FROM]->[THE NUMBER YOU DIALED] in context default
CLI, the command line interface, is one of the most useful tools when it comes to understanding what is going on in your system. Here you can look in real time at what is happening when you try to make or receive a call and you can diagnose faults. I have to say that this has been the most useful piece of information when it comes to diagnosing issues with the dial plan (apart from learning to write regular expressions). To run the cli you type /usr/local/freeswitch/bin/fs_cli at the linux prompt. If you don't want to look real time you can also look at the logs in /usr/local/freeswitch/log/freeswitch.log. Note that if you are using the console of your server then you really need to be looking at the log as that way you'll be able to scroll back and forward using your text file viewer and see what you need to see. But if you use PUTTY you can use the cli as you'll be able to scroll back and forward using the scroll bar on the side of the putty window. Note that the putty line buffer is set to 200 lines by default - I tend to increase this to 2000 so that I have enough history to scroll back through.
When you are using the CLI you can exit the CLI back to the linux prompt by typing ... (yes, three fullstops in a row, or for Americans, 3 periods in a row). To diagnose dial plan faults, start the CLI and then dial the number you want to test using your phone. You will see a bunch of stuff flying past. You'll then hear your call failure (if you didn't have a call failure you wouldn't be diagnosing it would you...) and at that point press CTRL-S to freeze the CLI output until you are finished looking at it.
So you're looking at the log. Look for a line like this one:
2010-08-12 09:20:21.736881 [INFO] mod_dialplan_xml.c:331 Processing [THE NAME OF YOUR PHONE EXTENSION YOU DIALED FROM]->[THE NUMBER YOU DIALED] in context default
It could be quite a way back up the log so don't give up looking. What happens after this is that you'll see a number of lines with the words "Regex (FAIL)" in them. This is not bad. What is happening is that your number is being compared to each regular expression in the dial plan in turn, and when it gets through the parts of the dial plan you have configured it then goes through the default dial plan (in dial plan, advanced) and compares each expression with your number. When it finds a match you will get a "Regex (PASS)". This pass is the key to diagnosing your problem. The thing about FusionPBX (maybe also Freeswitch for that matter) is that there are a LOT of functions already defined for you and they don't seem to have any sort of consistent pattern or number range that they are in (unlike Trixbox where you can see all of these in "Feature Codes" and most of them are * followed by a 2 digit number) therefore it is quite possible that what you are trying to set as your dial sequence is already matching one of the pre-defined functions and therefore it isn't working for you. It would also appear that some of these functions are defined in the dial plan BEFORE the things that you define in the dial plan, as putting your dial plan entry with an order of 0 still doesn't override them. So look at the PASS line and see which regular expression it matches, and the bits on the lines following that will give you clues as well. If it isn't the regular expression that you configured then it is likely you are in conflict with one of the already defined functions and you are just going to have to change yours.
The other possibility is that your regular expression is wrong - but you can test your regular expression with a number of automatic testing pages on the internet to see if that is the problem - the one I like is http://erik.eae.net/playground/regexp/regexp.html because you can cut and paste your regular expression into the first box, and then type your dial sequence into the second box, and then in real time, the third box gives you the interpreted result and even breaks it up into the different number groupings caused by your use of () in the regular expression.
Hopefully this will help make your dial plans easier to test and troubleshoot.
Dial plans - some recipes
Dial plans are a little complicated to work out, so this section is going to grow over time as I think to document more ways of doing things. Each item will be in the form of a scenario followed by the solution to it. I'll try not to use just simple examples each time, so that in each one we learn a little more than the basic scenario requires.
Scene 1:
You want a person to dial an abbreviated code to reach an external number, the abbreviated code might be a number that looks like an extension but the number you reach might be a mobile phone number for instance. In our example we'll use 1002 - a typical extension number. We must start the number with ^ and end it with $ - that is a requirement for a regular expression.
tag=condition
type=destination_number
data=^1002$
tag=action
type=bridge
data=sofia/gateway/your_gateway_name/the_external_number_you_wish_to_be_called
What will happen is that FusionPBX will see you dial 1002 and it will connect your call to the external number. Simple!
Scene 2a:
What about a situation where you want a number you dial to be sent out a specific trunk, different to the default routes you have set up in other dial plan entries? For instance, I have a trunk on my system that I use just for business calls so that I can track the cost on that independently to personal calls. I have a number I regularly need to call for business and I want it to automatically be on the business trunk. Since I regularly call it I also want to be able to use a short dial sequence for it too. Not only that, but when I go to my company office and dial it from there I have to dial 0 before I dial the number, so when I am doing it from home sometimes I make the mistake and dial 0 first out of habit and therefore I want that to succeed also.
tag=condition
type=destination_number
data=^(\*627|0?the_external_number_I_am_dialing)$
tag=action
type=bridge
data=sofia/gateway/your_gateway_name/the_external_number_I_am_dialing
In this example, my short dial is *627. In order to make the * be seen as an actual character to be dialled rather than a regular expression character I have to preceed it with \ which tells freeswitch to read the * as a * not as having a special meaning.
In the example as well you will see the | character. This tells freeswitch that I can either dial *627 OR whatever is after the | and they should both be considered a match with this dial plan entry. You can put as many of these | together as you like eg \*627|1110|174538 would let me dial either *627 or 1110 or 174538 and each of these would result in the same action taking place. After the | you will see 0? - the ? means that the digit before it is optional. If it said 0?1111 then this expression would be valid if I dialled either 01111 or 1111 on its own. So this allows me to handle my confusion between dialing at home where 0 is not necessary or dialing at work where 0 is necessary for an outside line (in some countries this is typically 9 rather than 0 and you can do this with 9?). So if I make the mistake at home and dial 0 it will still work as expected.
Lastly you will see that I have shown both the external_number_I_am_dialing in the condition AND in the action. This is because I said I wanted to be able to dial my short dial of *627 OR the full number OR 0 followed by the full number and I want all of them to succeed and to go down the correct trunk - specified by your_gateway_name in my example.
Scene 2b:
Although I mostly dial a few specific numbers from home that I want to be charged to my work account, there are times that I need to return a call for someone and so I can't list all of these numbers in my phone system as specific dialplan entries to go onto my work trunk. Effectively we are setting up a special trunk selector prefix that will cause the call to use a specific trunk (in my thinking trunk=gateway - they appear to be almost synonyms). To solve this I set up a special prefix in my dialplan.
tag=condition
type=destination_number
data=^11(\d*)$
tag=action
type=bridge
data=sofia/gateway/your_gateway_name/$1
In this example, my prefix is 11 and any time I dial this I want whatever number that follows to be dialled using my work trunk. In the condition we see \d*, as mentioned earlier, \* means the * character. In this instance * is not preceeded by \ and therefore it has a special regular expression meaning. That meaning is "whatever character comes immediately before the * can be repeated infinitely and it will still match." Therefore we can type as many \d characters as we like and it will be valid. But what is \d? That means ANY digit. Therefore when we say (\d*) we are saying any digit any number of times.
Therefore 110011155555555 will be valid but also 1155555555 will also be valid. We are saying here that you can dial ANY number after the 11 and it will be valid. This is good at home for me, but you wouldn't create this sort of entry on a business phone system because people could dial the trunk selector (11) and then could dial any number at all and ring up massive charges by calling adult chat lines etc. which most companies wisely block from being usable from the office phone system.
So a better way of doing this is to create an entry like this for each of the valid number ranges you wish to be able to dial. ie. duplicate your standard dialplan but prefix it with 11. At least, this is my recommendation until I can find a way of making a generic dialplan that doesn't require me to specify the gateway being used at the time of validating the number that is dialled. Anyone who has a better way is welcome to provide comments.
Incidentally, originally I wanted to use *8 as my prefix (which would have been written in the dialplan as \*8) however this clashed with some of the internally defined dial plan functions (something to do with eavesdrop I think) so I decided to use 1 as the first digit of any special function since no phone numbers I am aware of in Australia are permitted to start with 11.
More Scenes still to come...
Incidentally, originally I wanted to use *8 as my prefix (which would have been written in the dialplan as \*8) however this clashed with some of the internally defined dial plan functions (something to do with eavesdrop I think) so I decided to use 1 as the first digit of any special function since no phone numbers I am aware of in Australia are permitted to start with 11.
More Scenes still to come...
Configuring settings, trunks and extensions
This is quite self explanatory using the information available on the internet already so I'm going to assume you don't need my help on this (just for now), but I will come back and complete this later.
Voicemail to email
There will be more later but just a note to start for now. If you want to set up voice mail to email you will need to configure your SMTP server settings in system-settings. You will also need to configure the destination account in the settings for each extension. Note that FusionPBX does not use an MTA (Message Transfer Agent eg. sendmail or postfix) and instead uses a PHP script that acts as an SMTP client and connects to the SMTP server using the account and password you specify. As a result, there is no where you can see if your message was sent or not as there are no queues and no logs. However, if the php script executed (whether it successfully sent or not) there will be a file in /tmp called voicemailtoemail.txt - if this has been created and you didn't ever receive it then the script has executed but it either didn't successfully talk to the SMTP server OR it sent the message successfully but you didn't set the destination email account correctly. If the file ISN'T present in /tmp then the likely issue is that your file and directory permissions to /var/www/fusionpbx/secure are incorrect. The voicemail script is v_mailto.php and it also uses v_config_cli.php. If either of these cannot be accessed by freeswitch then it will not run and the file in /tmp will not be created.
Voicemail to email
There will be more later but just a note to start for now. If you want to set up voice mail to email you will need to configure your SMTP server settings in system-settings. You will also need to configure the destination account in the settings for each extension. Note that FusionPBX does not use an MTA (Message Transfer Agent eg. sendmail or postfix) and instead uses a PHP script that acts as an SMTP client and connects to the SMTP server using the account and password you specify. As a result, there is no where you can see if your message was sent or not as there are no queues and no logs. However, if the php script executed (whether it successfully sent or not) there will be a file in /tmp called voicemailtoemail.txt - if this has been created and you didn't ever receive it then the script has executed but it either didn't successfully talk to the SMTP server OR it sent the message successfully but you didn't set the destination email account correctly. If the file ISN'T present in /tmp then the likely issue is that your file and directory permissions to /var/www/fusionpbx/secure are incorrect. The voicemail script is v_mailto.php and it also uses v_config_cli.php. If either of these cannot be accessed by freeswitch then it will not run and the file in /tmp will not be created.
A word on numbering schemes
This post is a later addition that I am submitting in the order that you would need it rather than when I wrote it. Before setting up your phone system you need to decide on a numbering scheme.
When I was using asterisk I used 3 digit extensions and I used *xxx for special functions such as toggling day/night switches and I used *xx for trunk overrides so that I could force a call through a particular gateway. However this doesn't work with FusionPBX as using *anything is fraught with difficulties caused by the default dial plan and pre-defined functions - so just don't try to use * for anything of your own and you'll be far better off.
Pre-defined in the dial plan is the ability to work with 3, 4 or 5 digit extensions. Therefore if you have a small implementation you might want to consider 3 digit extensions and allocate the last 100 (ie. 900-999) to be special functions such as toggling day/night switches, short dial sequences, etc. If you have a larger implementation you might want to have 4 or 5 digit extensions and to use the entire 3 digit range for special functions.
Whatever you decide, document the ranges you are going to use and be consistent. It will make your job a lot easier and might save you some of the pain I had to go through in moving from Trixbox to FusionPBX.
When I was using asterisk I used 3 digit extensions and I used *xxx for special functions such as toggling day/night switches and I used *xx for trunk overrides so that I could force a call through a particular gateway. However this doesn't work with FusionPBX as using *anything is fraught with difficulties caused by the default dial plan and pre-defined functions - so just don't try to use * for anything of your own and you'll be far better off.
Pre-defined in the dial plan is the ability to work with 3, 4 or 5 digit extensions. Therefore if you have a small implementation you might want to consider 3 digit extensions and allocate the last 100 (ie. 900-999) to be special functions such as toggling day/night switches, short dial sequences, etc. If you have a larger implementation you might want to have 4 or 5 digit extensions and to use the entire 3 digit range for special functions.
Whatever you decide, document the ranges you are going to use and be consistent. It will make your job a lot easier and might save you some of the pain I had to go through in moving from Trixbox to FusionPBX.
Upgrading FusionPBX to the latest
The ISO has a version of FusionPBX in it that was current prior to the creation of the ISO. You will want to upgrade this to the latest version. To do this, go to the status page and click on upgrade (toward the bottom of the page). The first time you do this it can take a while so be patient. Later upgrades will be much faster.
Once the upgrade is complete, you can go to admin, menu manager, restore default and admin, template manager, restore default. This will upgrade the menus and the templates to the latest version as well. The only reason you might not want to update these is if you have made your own customisations to the menus or the templates. In such a case I'm not sure how you upgrade these without impacting your customisations. If anyone has done this let me know.
Once you have completed the upgrade, it would be worth checking that the current version of FusionPBX is not using directory paths that weren't defined at the time the original ISO was created. Go to system-system settings and ensure that any of the fields that are named in bold are filled in. Any field that is not bold is optional.
Once the upgrade is complete, you can go to admin, menu manager, restore default and admin, template manager, restore default. This will upgrade the menus and the templates to the latest version as well. The only reason you might not want to update these is if you have made your own customisations to the menus or the templates. In such a case I'm not sure how you upgrade these without impacting your customisations. If anyone has done this let me know.
Once you have completed the upgrade, it would be worth checking that the current version of FusionPBX is not using directory paths that weren't defined at the time the original ISO was created. Go to system-system settings and ensure that any of the fields that are named in bold are filled in. Any field that is not bold is optional.
Migrating
Ok, so I have to make a confession at this point. This is not my first FusionPBX installation. My first one was when I accidentally installed it on an old laptop thinking it was a LiveCD and it formatted my laptop harddrive. I never intended to install it on that machine! But I did get it up and running there, with slightly broken audio because the processor was far too slow (the laptop is nearly 10 years old and wasn't top of the line at the time).
So as I got everything initially setup on that machine, I didn't want to go through the trouble of setting up things again that I had already got working on that machine. Therefore when I setup my new server, on the machine I had actually intended to install it on, I wanted to migrate as much as possible over from the old machine rather than starting again. So this blog entry is to provide notes to people in case they want to migrate settings from one FusionPBX to another. If you are not migrating from one FusionPBX to another you wouldn't do any of these steps, however, you might want to make a note of how to import recordings below as you could import your Trixbox recordings and put them on your FusionPBX machine if you wanted to make life easier for yourself (however, you would want to convert them to 8000Mhz WAV files if they aren't already before copying them to FusionPBX).
a. backup the database from the old machine (web admin home, backup, download) or alternatively you can pull it from /var/www/fusionpbx/secure/fusionpbx.db using PSFTP (secure FTP provided with Putty).
b. put it onto the new machine using PSFTP
c. on the console of the new machine -
cd /var/www/fusionpbx/secure
cp fusionpbx.db fusionpbxoriginal.db
cp the_uploaded_fusionpbx.db .
(Note that by using cp to copy the new file over the existing file we maintain the file permissions on the existing file. Note that it is not necessary to stop any processes on the machine etc before doing this.)
d. on the web administration screens go through each of the voice menu features you have made use of and open one item in each and save it (no need to make any changes). Once you've done that for each feature you can apply your changes and it will have all taken effect. - note that you may be able to avoid this step if you copy the /usr/local/freeswitch/scripts folder from your old server to the new one - I haven't tried this but theoretically it will work.
e. you will need to reload the xml file, rescan your external and internal connections and then restart these - you do this all from the status webpage.
f. you will need to transfer any of your recordings such as voicemail greetings and IVRs etc from the old machine to the new one (/usr/local/freeswitch/recordings on FusionPBX. If you are copying these from Trixbox look in /var/lib/asterisk/sounds). You'll need to apply the same permissions to these files as is on the folder you are putting them into (using chmod, chgrp, chown).
g. voicemails greetings are stored in /usr/local/freeswitch/storage/voicemail/default/IPADDRESSOFYOURMACHINE/EXTENSION - you can copy them to your new machine using sftp - they will be "greeting_X.wav" and "recorded_name.wav" where X is the greeting number. The greeting will not actually play until you dial into the voicemail for that extension and select that greeting number, then it will be active. Personally I would not bother copying these - it would be better to re-record all of the outgoing messages. Also, you would want to have listened to all your incoming messages before migrating as you don't want to have to copy those.
h. if you made any customisations to the sip profiles you'll have to manually copy those changes over as well as they are not stored in the database. Look for these in /usr/local/freeswitch/conf/sip_profiles
i. if you made any custom scripts you will need to transfer these manually too. Theoretically you would have stored these in /usr/local/freeswitch/scripts. But if not, you created them, so hopefully you know where you put them!
So as I got everything initially setup on that machine, I didn't want to go through the trouble of setting up things again that I had already got working on that machine. Therefore when I setup my new server, on the machine I had actually intended to install it on, I wanted to migrate as much as possible over from the old machine rather than starting again. So this blog entry is to provide notes to people in case they want to migrate settings from one FusionPBX to another. If you are not migrating from one FusionPBX to another you wouldn't do any of these steps, however, you might want to make a note of how to import recordings below as you could import your Trixbox recordings and put them on your FusionPBX machine if you wanted to make life easier for yourself (however, you would want to convert them to 8000Mhz WAV files if they aren't already before copying them to FusionPBX).
a. backup the database from the old machine (web admin home, backup, download) or alternatively you can pull it from /var/www/fusionpbx/secure/fusionpbx.db using PSFTP (secure FTP provided with Putty).
b. put it onto the new machine using PSFTP
c. on the console of the new machine -
cd /var/www/fusionpbx/secure
cp fusionpbx.db fusionpbxoriginal.db
cp the_uploaded_fusionpbx.db .
(Note that by using cp to copy the new file over the existing file we maintain the file permissions on the existing file. Note that it is not necessary to stop any processes on the machine etc before doing this.)
d. on the web administration screens go through each of the voice menu features you have made use of and open one item in each and save it (no need to make any changes). Once you've done that for each feature you can apply your changes and it will have all taken effect. - note that you may be able to avoid this step if you copy the /usr/local/freeswitch/scripts folder from your old server to the new one - I haven't tried this but theoretically it will work.
e. you will need to reload the xml file, rescan your external and internal connections and then restart these - you do this all from the status webpage.
f. you will need to transfer any of your recordings such as voicemail greetings and IVRs etc from the old machine to the new one (/usr/local/freeswitch/recordings on FusionPBX. If you are copying these from Trixbox look in /var/lib/asterisk/sounds). You'll need to apply the same permissions to these files as is on the folder you are putting them into (using chmod, chgrp, chown).
g. voicemails greetings are stored in /usr/local/freeswitch/storage/voicemail/default/IPADDRESSOFYOURMACHINE/EXTENSION - you can copy them to your new machine using sftp - they will be "greeting_X.wav" and "recorded_name.wav" where X is the greeting number. The greeting will not actually play until you dial into the voicemail for that extension and select that greeting number, then it will be active. Personally I would not bother copying these - it would be better to re-record all of the outgoing messages. Also, you would want to have listened to all your incoming messages before migrating as you don't want to have to copy those.
h. if you made any customisations to the sip profiles you'll have to manually copy those changes over as well as they are not stored in the database. Look for these in /usr/local/freeswitch/conf/sip_profiles
i. if you made any custom scripts you will need to transfer these manually too. Theoretically you would have stored these in /usr/local/freeswitch/scripts. But if not, you created them, so hopefully you know where you put them!
That's everything I've found. If you try it and you come up with anything else that it is helpful to migrate or any alternative steps then please submit them as comments so everyone can be helped by your insight.
Getting Started
So I downloaded the Centos ISO (Note: The ISO is currently not available on the FusionPBX website as it was lost in a server failure a few months ago. A new version of the ISO is being created and will be posted there (http://fusionpbx.com/download.php) once it is ready, but in the meantime, you can get the old one from here: https://docs.google.com/leaf?id=0B5JYtyKSDpNbOTU2YWQxMmYtMmM4Yy00MWI0LWExZDktMDlkZjY4MDFlZDg5&hl=en&authkey=CJDZhRQ) and burnt a CD. Don't make the mistake of thinking it is a LiveCD! You do not get to try this out before installing it. When you put this in your machine and boot it it WILL erase your harddrive without checking first! Ok, so it happened to me. Fortunately it was my test machine but I did lose some things I had been working on.
So boot your machine from the ISO and let it install on the harddrive. This is a MUCH simpler process than for Trixbox. Trixbox requires you to answer a bunch of install questions before it installs, FusionPBX just gets on with the job and installs itself. Very neat.
While it is installing, take the time to download PUTTY from this link http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html. In my view, the best package to use is the Windows installer package there as it contains everything. Putty is used to create a secure telnet type session with your freeswitch server. This means that you don't have to work at the console and you can cut and paste commands you find here or elsewhere on the internet directly to your freeswitch linux prompt. Wherever I refer to working at the console in this blog you can directly substitute working via putty. PSFTP which is also in the Windows installer package allows you to securely FTP files to and from your server. I consider both of these essential tools for use with FusionPBX/Freeswitch.
Once FusionPBX has installed log in on the console using the default account and password (root, fusionpbx). Then change the password with the passwd command before you forget. The next job is to get it up and running with an IP address. system-config-network will allow you to set the IP address (or take the default of DHCP). You don't really want to use DHCP if you are building a real production system as your telephones need to be able to find it easily, but then again, you could reserve an address in your DHCP server for it, and then it will always have the same address anyway - so it is up to you. I'm using DHCP, I suspect I could therefore skip this step but I haven't tried.
service network restart will actually start the network service. If it says fail then you have a problem. In my case it did - I had two network cards in my machine (don't ask) and it started the first one and not the second - and my network cable was plugged into the second. Swapping the cable fixed the problem for me and I was able to start it when I tried the command again.
Now there are some errors in the current ISO (May 2010) so you'll need to correct them and since we have to do it at linux level we should do it now. (now don't complain - the errors are just permission issues and they are easily fixed, and I'm telling you how to fix them. The actual software is excellent)
- To get voicemail working:
chmod -R 775 /usr/local/freeswitch/storage
chgrp freeswitch /usr/local/freeswitch/storage
- To make it so that FusionPBX can see the recordings you make for menus etc:
chmod -R 775 /usr/local/freeswitch/recordings
- To get the voicemail mailer application working:
chown -R apache:daemon /var/www/fusionpbx
chmod -R 776 /var/www/fusionpbx
(My thanks go to Mark Crane - the author of FusionPBX - for his help in identifying these corrections)
UPDATE 17-August-2010:
- To get Call Detail Reporting working:
- chmod -R 777 /usr/local/freeswitch/log
UPDATE 24-September 2010:
Next we should set the time and timezone. First we update the timezone information on the machine. This ensures that the latest changes by governments around the world that have made it into linux are incorporated on your box (would you believe that some countries change their timezone information every year by moving their daylight savings start and finish dates?).
yum -y update tzdata
Next we need to identify the timezone for you to use. Look in /usr/share/zoneinfo and identify your timezone - you will need to note the folder and the filename eg. Australia/Sydney.
Now we create a symbolic link to the timezone information so that when it is updated you get the benefit of the update (you could just copy it but then it would no longer update).
ln -sf /usr/share/zoneinfo/Australia/Sydney /etc/localtime
We also need to edit the clock information.
nano /etc/sysconfig/clock
The current ISO was created in Kolkota, India, so you will need to change the timezone from Asia/Kolkota to the same zone as you identified above, although if you are in Kolkota you actually don't need to do any of these changes, at least for the present ISO. Save your changes to the file once you are finished.
Now we set the current time from a time server.
ntpdate us.pool.ntp.org
We check the time is correct:
date
hwclock
Since we don't want to have to check the clock periodically and re-set it we can set it to maintain the time from time servers on the internet.
/sbin/chkconfig --level 345 ntpd on
This will set ntpd to automatically run - by default in the CentosISO for FusionPBX it is disabled. Next we start the ntpd service now (otherwise it would only start when we next reboot).
/sbin/service ntpd restart
Incidentally, you can see what the ntp daemon is doing if you type ntpq -p localhost
At this point you can now forget linux (log off first!) and you can start using the GUI. Point your browser to it with http://your-server-IP-address and start setting up the machine. But hold on, if you chose DHCP how do you know what the IP address is? Good question. Unfortunately when I first wrote this I didn't know enough about linux to know how to find out from the linux prompt (I've since learnt that the command is ifconfig). In my case I logged into my DHCP server and looked to see what address it had just issued to the server, and then I browsed to it using that address.
The final step before your machine is installed is that when you log in to the web page the first time (note that the logins are superadmin and admin and the default password is fusionpbx for both) you will need to confirm some installation settings. The simplest thing is to accept all the default settings, so just scroll down and click to continue. Next, change the default passwords by going to the admin menu and selecting user manager. Click on the icon with the "e" in it, in the user list, next to the user account you want to change and then change the password and save the changes. Do this for superadmin and admin.
You are now done! Your PBX is up and running. (But it isn't doing anything yet - more in the next post)
So boot your machine from the ISO and let it install on the harddrive. This is a MUCH simpler process than for Trixbox. Trixbox requires you to answer a bunch of install questions before it installs, FusionPBX just gets on with the job and installs itself. Very neat.
While it is installing, take the time to download PUTTY from this link http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html. In my view, the best package to use is the Windows installer package there as it contains everything. Putty is used to create a secure telnet type session with your freeswitch server. This means that you don't have to work at the console and you can cut and paste commands you find here or elsewhere on the internet directly to your freeswitch linux prompt. Wherever I refer to working at the console in this blog you can directly substitute working via putty. PSFTP which is also in the Windows installer package allows you to securely FTP files to and from your server. I consider both of these essential tools for use with FusionPBX/Freeswitch.
Once FusionPBX has installed log in on the console using the default account and password (root, fusionpbx). Then change the password with the passwd command before you forget. The next job is to get it up and running with an IP address. system-config-network will allow you to set the IP address (or take the default of DHCP). You don't really want to use DHCP if you are building a real production system as your telephones need to be able to find it easily, but then again, you could reserve an address in your DHCP server for it, and then it will always have the same address anyway - so it is up to you. I'm using DHCP, I suspect I could therefore skip this step but I haven't tried.
service network restart will actually start the network service. If it says fail then you have a problem. In my case it did - I had two network cards in my machine (don't ask) and it started the first one and not the second - and my network cable was plugged into the second. Swapping the cable fixed the problem for me and I was able to start it when I tried the command again.
Now there are some errors in the current ISO (May 2010) so you'll need to correct them and since we have to do it at linux level we should do it now. (now don't complain - the errors are just permission issues and they are easily fixed, and I'm telling you how to fix them. The actual software is excellent)
- To get voicemail working:
chmod -R 775 /usr/local/freeswitch/storage
chgrp freeswitch /usr/local/freeswitch/storage
- To make it so that FusionPBX can see the recordings you make for menus etc:
chmod -R 775 /usr/local/freeswitch/recordings
- To get the voicemail mailer application working:
chown -R apache:daemon /var/www/fusionpbx
chmod -R 776 /var/www/fusionpbx
(My thanks go to Mark Crane - the author of FusionPBX - for his help in identifying these corrections)
UPDATE 17-August-2010:
- To get Call Detail Reporting working:
- chmod -R 777 /usr/local/freeswitch/log
UPDATE 24-September 2010:
From the designer of FusionPBX - if you are strict with permissions, freeswitch needs execute and read for the /var/www/fusionpbx/secure directory in order to be able to run the php command line files in that directory. Every other directory within the fusionpbx directory structure only needs read and write permission.
UPDATE 24-October 2010:
- To create voicemail boxes (this is done by freeswitch on the fly when one is needed) you need to do
chown -R freeswitch:apache /usr/local/freeswitch/storage
UPDATE 24-October 2010:
- To create voicemail boxes (this is done by freeswitch on the fly when one is needed) you need to do
chown -R freeswitch:apache /usr/local/freeswitch/storage
Next we should set the time and timezone. First we update the timezone information on the machine. This ensures that the latest changes by governments around the world that have made it into linux are incorporated on your box (would you believe that some countries change their timezone information every year by moving their daylight savings start and finish dates?).
yum -y update tzdata
Next we need to identify the timezone for you to use. Look in /usr/share/zoneinfo and identify your timezone - you will need to note the folder and the filename eg. Australia/Sydney.
Now we create a symbolic link to the timezone information so that when it is updated you get the benefit of the update (you could just copy it but then it would no longer update).
ln -sf /usr/share/zoneinfo/Australia/Sydney /etc/localtime
We also need to edit the clock information.
nano /etc/sysconfig/clock
The current ISO was created in Kolkota, India, so you will need to change the timezone from Asia/Kolkota to the same zone as you identified above, although if you are in Kolkota you actually don't need to do any of these changes, at least for the present ISO. Save your changes to the file once you are finished.
Now we set the current time from a time server.
ntpdate us.pool.ntp.org
We check the time is correct:
date
We set the bios clock to match the system clock.
hwclock --systohc
We check that it worked.hwclock
Since we don't want to have to check the clock periodically and re-set it we can set it to maintain the time from time servers on the internet.
/sbin/chkconfig --level 345 ntpd on
This will set ntpd to automatically run - by default in the CentosISO for FusionPBX it is disabled. Next we start the ntpd service now (otherwise it would only start when we next reboot).
/sbin/service ntpd restart
Incidentally, you can see what the ntp daemon is doing if you type ntpq -p localhost
At this point you can now forget linux (log off first!) and you can start using the GUI. Point your browser to it with http://your-server-IP-address and start setting up the machine. But hold on, if you chose DHCP how do you know what the IP address is? Good question. Unfortunately when I first wrote this I didn't know enough about linux to know how to find out from the linux prompt (I've since learnt that the command is ifconfig). In my case I logged into my DHCP server and looked to see what address it had just issued to the server, and then I browsed to it using that address.
The final step before your machine is installed is that when you log in to the web page the first time (note that the logins are superadmin and admin and the default password is fusionpbx for both) you will need to confirm some installation settings. The simplest thing is to accept all the default settings, so just scroll down and click to continue. Next, change the default passwords by going to the admin menu and selecting user manager. Click on the icon with the "e" in it, in the user list, next to the user account you want to change and then change the password and save the changes. Do this for superadmin and admin.
You are now done! Your PBX is up and running. (But it isn't doing anything yet - more in the next post)
FusionPBX for ex-Trixbox users
Since this is the start of a new blog I should set out my premise for doing this.
For several years now I have been a dedicated user of Trixbox PBX but I have reached the point where I need to change. The main factors being that there is a bug in the present version of Trixbox (and no easy upgrade path to the next version) that prevents DTMF tones from being correctly interpreted at a remote destination and therefore complicates the use of telephone banking systems and conference call systems which require DTMF entries, and there is a lot of stuff that you need to do at the OS level if you want things to work smoothly (eg. sending email).
So I looked around and liked the concept of FreeSwitch and looked for a GUI for it and discovered FusionPBX. FusionPBX is well presented and actively maintained. It seemed easy enough to use and so I burnt myself a Centos ISO CD and got started.
But more on that later. There is one more thing to say first. FusionPBX has capabilities to allow you to program the dial strings in the same format as Asterisk. I will not be making use of these features as my intention is to learn FusionPBX and to use it the way it is intended. So as I go through this I'll be documenting how to do things the FusionPBX way. That said, I chose the Centos version of FusionPBX because I was comfortable with it, having used it for so long with Trixbox.
So since we're moving to a new and fresh VOIP environment I thought I'd choose a blog layout that looks new and fresh, and slightly out of focus. We'll say that the out of focusness of it represents the fact that right now fusionpbx looks good but is out of focus because we don't understand it yet. And no, I'm not going to be changing the background to a more focussed one as we progress for two reasons (a) it is too much trouble and (b) there are always going to be new things we can learn about FusionPBX and new things we can make it do, so it will never fully be in focus.
So since we're moving to a new and fresh VOIP environment I thought I'd choose a blog layout that looks new and fresh, and slightly out of focus. We'll say that the out of focusness of it represents the fact that right now fusionpbx looks good but is out of focus because we don't understand it yet. And no, I'm not going to be changing the background to a more focussed one as we progress for two reasons (a) it is too much trouble and (b) there are always going to be new things we can learn about FusionPBX and new things we can make it do, so it will never fully be in focus.
Subscribe to:
Posts (Atom)