Debugging About Welcome to FreeSWITCH debugging! As with all major software projects there will be occasional issues. You want your issue fixed quickly. We want your issue fixed quickly. The best way to quick resolution is to follow a few steps presented here. You will need to familiarize yourself with a few tools: The checklist for reporting issues PLEASE READ THIS FIRST Git - http://fisheye.freeswitch.org/browse/freeswitch-git pastebin - http://pastebin.freeswitch.org (username/password displayed in challenge box) JIRA - http://jira.freeswitch.org (issue tracker, reg req'd) IRC - irc.freenode.net, channel name #freeswitch GDB (possibly) Important Note, Please Read Please don't report bugs on the mailing list. Please. What should you do if you are experiencing unexpected behavior, but you don't know if it's a bug or a configuration issue? Take these steps: Hop on the IRC channel and ask if anyone is familiar with the situation Search the wiki for the symptoms you are experiencing Search the mailing list history for the symptoms you are experiencing Search Jira for the symptoms you are experiencing Here's what not to do: Send an email to the mailing list with lots of information and asking, "Is this a bug?" Do this instead: open a Jira ticket and then you can send a message to the list. Say something like, "I opened Jira ticket xxx because I'm having behavior yyy when I do zzz. I don't know if this is really a bug, so I'm open to suggestions." See the rest of this page for more information on how to interact on the IRC, mailing lists and how to file a Jira. Standard Disclaimer Sometimes FreeSWITCH users and experts will offer suggestions on the mailing list ("ML" for short) or the IRC channel. The standard disclaimer goes something like this: I didn't test this myself, so you need to test thoroughly before telling me it doesn't work It may have typos - please look for them before telling me it doesn't work I may have forgotten something - please research any errors before telling me it doesn't work I may be totally wrong - please research the solution before telling me it doesn't work In other words, when someone gives you a suggestion and it doesn't work on the first try, please make an attempt to figure out what the person was trying to accomplish and see if you can figure it out yourself. If, after concerted effort, you are unable to get it to work or you hit a roadblock that you cannot overcome only then should you report back that the suggestion did not work. Many times the suggestion may not work but it might get you going in the right direction. When that happens please report back what you found and how you resolved your issue. We like hearing that stuff. :) Fast Tracking your Bugs to Get Fixed Sooner If you would like your issue resolved in the fastest manner, without having to pay to have support do it, these are some tips that will help greatly with the process: Follow the instructions on this page, make sure to be detailed when possible If it is something that you know worked in the past and doesn't work now see Using Git Bisect for helping us track down exactly what commit it broke in. As long as you can use the command line you can test with this method and it will greatly speed up bug fixing. If you know what's wrong and are able to change the code to make the fix then see Creating Patches With Git. A JIRA issue that has a patch just needs the code reviewed and tested is about the fastest way to have a ticket resolved. Finally when Reporting A Bug make sure you submit concise repro steps and as much log data as can support the issue. To easily collect and submit log data and sip traces see fs_logger.pl. It can collect all the log data, sip traces, and even submit individual files up to the pastebin. If needed it can obfuscate log data to remove sensitive information prior to posting. fs_logger.pl is very easy to use and doesn't have any dependencies other than fs_cli on the box. It works in windows and linux and for windows users without perl there is a compiled exe that can be used. For some easy getting started with fs_logger.pl see the Helping Others with fs_logger.pl section. It is recommended when filing a ticket to attach the raw pastebin content to the ticket rather than linking so it is preserved (as pastebin entries can and do go away after a certain amount of time). Debugging Steps We need to know if your issue is really a bug, so there are some things to do, like updating to the latest software and getting some captures of the command line. Get The Latest Code Please do not report a bug without trying the latest Git! The very first thing the community will ask you is, "Have you tried it on latest Git?" Save yourself the time and update before reporting the bug. FreeSWITCH is evolving quickly, so the problem you may be experiencing might already have been fixed. Linux Git If installed by using the snapshot or doing a Git clone then updating is extremely simple. In the FreeSWITCH source directory: make current Now, shutdown FreeSWITCH and start it again. That's it! Wait for the system to refresh, and then see if you can reproduce your symptoms. Windows Git Use your Git client (like TortoiseGit) to update to the latest Git Re-open the solution file and then click Build > Rebuild Solution Run FreeSWITCH again and see if you can reproduce the symptoms. If you are using a pre-compiled binary, such as a DEB or RPM (or MSI file in Windows) then you have some work to do. Your best bet is to do a fresh checkout and see if you can reproduce the symptoms on a clean install. Make a backup of your entire conf folder and then clear it out so that you can start with a fresh default configuration. You'll want to get the system working with the default config first, and then add your customizations to see if you can reproduce symptoms. Upgrading From Older Revisions If you are upgrading from an older revision, say from 1.0.1 to the latest Git, then you must do a few things: Copy your conf directory to a safe location, e.g. /usr/local/freeswitch/conf Completely remove the FreeSWITCH install directory, e.g. /usr/local/freeswitch Completely remove the FreeSWITCH source directory Do a fresh checkout and install, including "make samples" Carefully copy your configuration changes back to the conf directory You may want to launch FreeSWITCH prior to putting your customizations in place and confirm that all is working If the issue remains then it's time to ask for help, but first you'll need some basic knowledge on how to capture debug information. FreeSWITCH Command Line Most of your debugging information will come from the FreeSWITCH command line interface (CLI). It is important that you are able to capture the output that is displayed on the command line. This means that you will need to use a terminal program of some sort that can scroll back and copy, or one that can enable capturing of output. To put your console in debug mode, press F8 or type console loglevel 7 For more information about the console please see Mod_console Alternatively you can use the log file to capture specific information. NOTE: SIP trace messages (see "TPORT_LOG=1" below) will not go to the log files. An easy way to isolate specific debug information with the log files is to use a manual log file rotation. From the FreeSWITCH CLI: fsctl send_sighup This will rotate the log files. Reproduce the symptoms you are troubleshooting and then issue a second fsctl send_sighup command. You will have a relatively small log file in the log directory, at which point you can copy and paste that into the pastebin. More information about log files can be found here. Asking The Community For Assistance The FreeSWITCH community is very welcoming of new members and is ready to assist those who have questions. In return we ask that you take the time and effort to gather all of the information that is needed in order to diagnose your issue. Using The Pastebin The FreeSWITCH pastebin is a handy place for users to post information for other users or the developers to access easily. All pastebin posts will have an id. For example, this post has an entry number of a9ebaf6c. Frequent users will often abbreviate pastebin as "pb" and sometimes you will see notation like "pb a9ebaf6c" which, of course, refers to pastebin post number a9ebaf6c. For the sake of convenience, when submitting information to the mailing list, please paste the entire link and not an abbreviation. Also, if you are posting the output of a FreeSWITCH console log (or freeswitch.log file) then be sure to use "FreeSWITCH log" as the syntax highlighting when creating the pastebin entry. This makes it much easier to read through the logs. Note: If using Jira please attach the file as a .txt file to the Jira rather than referencing pastebin.freeswitch.org. This helps make sure the reference doesn't get lost because the pastebins timeout.