Reporting Bugs

From FreeSWITCH Wiki
Jump to: navigation, search

Contents

Introduction

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:

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 open 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 whats wrong are are able to change the code to make the fix then see Creating Patches With Git a jira 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. Either paste log data on pastebin or attach it to the ticket but its generally preferred you do not include the log data in the body of the ticket as it makes it harder to read.

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 a number. For example, this post has an entry number of 6750. Frequent users will often abbreviate pastebin as "pb" and sometimes you will see notation like "pb 6750" which, of course, refers to pastebin post number 6750. 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.

Pro Tip: Use this URL format to download a pastebin entry as text:

http://pastebin.freeswitch.org/pastebin.php?dl=####

Where #### is the pastebin entry number.

Using The IRC Channel

The #freeswitch channel on irc.freenode.net is a good place to chat in real-time with FreeSWITCH developers, power users, and other new users. Please use proper chat room etiquette and be mindful that there are many people from around the world in the chat room. Be patient, even when others are not. Be kind, even when others are not. Don't take anything personally.

You will need an IRC client, or you can use the link on the main FreeSWITCH page. We recommend you learn some about how to use IRC. Here are some resources:

When you log in to the channel you can ask your question simply by asking it. No need to ask permission to ask a question. Sometimes there is a high volume of traffic, in which case you might be prompted to use the "take-a-number" system. It works like this:

~take-a-number Could someone tell me if there is a wiki page that discusses regular expressions?

In either case, please wait for a response. It could take a few minutes to a few hours depending on the time of day. Most FreeSWITCH developers and power users are are located in the Americas, however there is a growing number of users from around the globe. If you are not in a position to sit on the chat channel and wait then it would be good to ask your question on the user list.
One other piece of advice: please be nice to c888 when in the IRC channel.

FreeSWITCH Users Mailing List

The FreeSWITCH project maintains mailing lists here. Please join the mailing list so that you can send and receive emails along with the rest of the community. Emails to the users list should be addressed to freeswitch-users@lists.freeswitch.org. Please use a descriptive subject name and include as much detail as reasonably possible in the message body.

Subject Lines

Some examples of good subject lines

  • FreeSWITCH Crashes When Calling Application "foo"
  • Feature "xyz" stopped working when I upgraded to latest trunk
  • Dialplan question: how do I use "foo"?
  • Help With xxx Error When Using Gateway

Some not-so-good subject lines

  • HELP!!!!
  • FreeSWITCH crashes!!!
  • What's Wrong?
  • This is broken!

Message Body

The message body should include as much information as possible. At the very least you should include what is in the Report_Issue_Checklist. We recommend that you use pastebin for large posts (30+ lines). In some cases it is advantageous to put command line debug output into one pastebin post, dialplan entries in another post, custom scripts in another post, etc. The pastebin supports syntax highlighting so keeping unlike items in separate pastebins will make them easier to read. Also, using pastebin makes it easier to look up information than scrolling through email threads.

Following Up

Sometimes you might find more information about a bug report, perhaps after it has been filed but before it has been closed. It is quite common for people to open a report and then go back and start digging around. We encourage this! You'll learn a lot by doing so and you will also help the developers by doing some of the research and legwork.

Reporting More Information

If you have more information on a question that you previously posted to the list then please reply to the thread with the additional information. Also, please DO NOT include the ENTIRE email thread in your reply as that makes it more difficult to find the relevant information.

Please Be Patient

You've reported a bug or asked a question and haven't heard anything in a few days. You're itching for a fix. It's okay to post a follow up question, but please be polite. Definitely do NOT accuse the developers of ignoring questions, bug reports or feature requests. Their workload is enormous, and much if it is pro bono. If you are in desperate need of a new feature then please send an email to consulting@freeswitch.org where paid support and custom work is available at reasonable rates.

Calling The FreeSWITCH Conference

Occasionally there will be times when users will need to speak live instead of via email or IRC. There are many ways to call the voice conference and they are listed here on the main page. Also, there are times when people call the voice conference just to hang out, so feel free to call in and see what is happening.

Debugging Specific Technologies

Most of the time you will be debugging some sort of SIP trouble or a crash, but there are also times when you are troubleshooting something more specific, such as analog or digital TDM calls, or the many different "hooks" that FreeSWITCH provides: Lua/Perl/JavaScript/etc., event socket, XML curl, LDAP, etc. Here are some specific guidelines for gathering information on various technologies.

Sofia/SIP

FreeSWITCH uses the Sofia-SIP stack; in many cases SIP and Sofia are interchangeable. Debugging SIP includes keeping in mind that your voice traffic is going over a data network and therefore devices on the network may affect your VoIP traffic.
Here are some things to keep in mind:

  • NAT/Firewalls will cause problems if not properly configured
  • Routers, Switches, and cabling can affect call quality
  • Network traffic and QoS can also affect call quality

These are things that aren't voice specific so it may be necessary to get your network administrator.

Turning On SIP Trace

In many cases it is critical to see the raw SIP messages. These can be displayed to (and captured from) the console. In Linux/Unix start FreeSWITCH like this:

TPORT_LOG=1 /usr/local/freeswitch/bin/freeswitch

To stop the SIP trace you will need to stop and restart FreeSWITCH without the TPORT_LOG environment variable set. See here for more information on SIP tracing.

Quick and Easy SIP Trace

The above commands are still available, however since version 1.0.6 there have been some handy sofia commands that make SIP traces easier to get. Without restarting FreeSWITCH you can use these commands:

  • sofia profile xxx siptrace on
  • sofia profile xxx siptrace off
  • sofia global siptrace on
  • sofia global siptrace off

The first two commands will enable/disable SIP trace on a specific profile. The second two commands will enable/disable SIP trace on all profiles simultaneously.

Capturing RTP With tshark (Advanced)

tshark -o "rtp.heuristic_rtp: TRUE" -R sip\|\|rtp\|\|rtcp -w test.pcap

Even more advanced packet capture information is available here.

Making The pcap File Available

Packet captures are generally large files, so it's best to put them out on a server where we can use a tool like wget or a browser to download them. If you don't have access to a server then use a service like YouSendIt. You can upload the file and then provide us with the link to download it.

FreeTDM/TDM

Traditional telephony, or Time-Division Multiplexing (TDM), is handled in FreeSWITCH by the FreeTDM abstraction layer. It is important to provide copies of your FreeTDM configuration files as well as any dialplan entries that use FreeTDM:

  • freetdm.conf file
  • freetdm.conf.xml file

There are basically three flavors of TDM which are covered in the next section.

Analog

Analog cards, such as the Sangoma A200, Digium TDM400 or clones X100P/X101P, are for traditional POTS lines. There are two types of analog ports:

  • FXS - Supplies dial tone
  • FXO - Accepts dial tone

Please note which kind of ports you are using when asking for help.

CAS/RBS

When using CAS/RBS please specify which type of signaling you wish to use. (There is also a nice introductory discussion of this topic in a Wikipedia article.)

ISDN

ISDN comes in two general forms: PRI and BRI. When reporting issues please make a note of which protocol dialect you are using:

  • DMS - Nortel DMS100
  • 5ESS - AT&T/Lucent (used for 4ESS also)
  • Q931 - Generic PRI, used for EuroISDN
  • National - NI2

Event Socket

Please specify if you are using inbound or outbound event socket.

Inbound

A key issue with socket programming is receiving the correct events. One thing to try is manually connecting to the event socket and subscribing to all events. The basic procedure on Linux is:

telnet 127.0.0.1 8021\n
auth ClueCon\n\n
events plain all\n\n

Note: "\n" here means "Press Enter" so don't literally type "\n"!
Now you may watch events, capture the output, etc. If you see something you believe to be unusual, please capture the output and include it with the information that you put into the pastebin.
To disconnect from the event socket:

exit\n\n

Outbound

Please provide a copy of the dialplan and script/shell command you are using. Please also describe the symptoms you are experiencing.

Scripting

To debug scripting it is critical that we be able to reproduce the issue. There are two ways to do this:

  • Create the smallest, simplest script that can reproduce the behavior
  • Give us the entire script

We do understand that there are proprietary concerns, so the developers and troubleshooters will be happy to keep such proprietary code in strict confidence. However, it is not acceptable that someone reports a bug with a script but then refuses to let us see the script that makes the behavior happen!

CPU Usage

Occasionally your system may exhibit signs of sluggishness. Sometimes this means that a particular process is misbehaving in some fashion. For Linux systems you have several tools at your disposal.

top

The top utility displays information about CPU, memory and disk usage for each process on the system. Use it to see which processes are using system resources. If a FreeSWITCH instance is using a lot of system resources then use "top -H" to find the particular thread that is acting up. Locate the process ID (PID) of the offender and then get ready to do a gcore...

gcore

Run gcore on the PID in question to generate a core file. Then run "thread apply all bt" to see what's going on. Most likely you'll need to capture this information and put it into pastebin and then ask one of the advanced FreeSWITCH users for assistance on the IRC channel. (Don't use the mailing list, please.) Most likely you'll need to open a Jira ticket, so be ready to do that. Also, see the next section ("example") for some specific steps for collecting information to put into the Jira.

example

In a recent ML thread Anthony mentioned these specific steps to identify what was causing one core to hit 100%:

  • update to latest
  • reproduce the symptom, in this case one core hitting 100% usage
  • cmd: top -H `cat /usr/local/freeswitch/run/freeswitch.pid`
    • find the process that is 100% and note its pid
  • cmd: gcore `cat /usr/local/freeswitch/run/freeswitch.pid`
    • note the file name produced by gcore
  • cmd: gdb `which freeswitch` <name of resulting file generated by gcore>
    • In gdb enter: "info threads"
    • look for the one with the same pid as the one you noted above
    • enter: thread <thread # that goes with the pid>
    • enter: bt

The output from the backtrace ("bt") will hopefully yield the necessary information about why the CPU usage spiked. As always, open a Jira with this information - don't send it to the -users list. If you wish to discuss the backtrace with other developers you can actually do that on the Jira comments. Those are public, so no need to overrun the mailing lists with these discussions.

XML Curl

  • TODO

Other Stuff?

  • TODO

Advanced Debugging Techniques

Creating A Backtrace With gdb (Linux/Unix)

If you are getting core dumps (aka Segmentation Faults or "segfaults") in Linux/Unix then it is important to get a backtrace, which is a tool for developers to examine what happened right up to the point where the program crashes. Any report of a segfault should be accompanied by a backtrace. Once you have a backtrace please put it into a pastebin posting on pastebin.freeswitch.org. Please do not use pastebin.com or some other pastebin website as this makes it difficult for us to find multiple related pastebin entries.

For further information on the very powerful gdb debugger see debugging-with-gdb

Important Note

You need to set /proc/sys/fs/suid_dumpable to a non-zero value (see man 5 proc), to enable core dumping for processes that switch their UID on startup (such as freeswitch with -u option).

By default, the freeswitch process will try to put the core file into the CWD (current work directory), so make sure the UID it is running as can write there (or "cd" into a different directory before starting it).

You might also want to check out man 5 core, for all the other options (e.g. piping core dumps into a custom handler, with core_pattern).

How to load coredump in gdb

From /usr/local/freeswitch:

$ gdb bin/freeswitch 

To load with a core file

$ gdb bin/freeswitch core.xxx

Getting a Backtrace

Once you load the core file into GDB you can collect a backtrace typing

bt
bt full
thread apply all bt
thread apply all bt full
  • To report a specific thread/pid

1) Update to the latest and try to reproduce first
2) If you can reproduce, then

cmd: top -H -p `cat /usr/local/freeswitch/run/freeswitch.pid`

find the process that is 100% and note its pid

cmd: gcore `cat /usr/local/freeswitch/run/freeswitch.pid`
cmd: gdb `which freeswitch` <name of resulting file generated by gcore>
enter: "info threads"

look for the one with the same pid as the one you noted above

enter: thread <thread # that goes with the pid>
enter: bt

3) Open a bug report in Jira

Simple bash script to make debug easy

In the source directory there is a support-d sub-directory. Inside this directory is a handy shell script called fscore_pb. The script will collect the appropriate trace (and some other information), post it to pastebin.freeswitch.org, and then give you the URL to give to the developers.

Usage:
 support-d/fscore_pb gcore [user]
 support-d/fscore_pb [user]

If gcore is given it will take a gcore of a running instance of FreeSWITCH (this will pause the process during the dump). If gcore is not given it will use the most recent core.* file in the directory.

User is optional, and is the name given when submitting the pastebin. If it is omitted it will use your local username.

Collecting Debug Information While FreeSWITCH Is Running (Linux/Unix)

Occasionally FreeSWITCH will become unresponsive. To help determine what is happening you can do a "g-core" and report the results. Please follow these steps:

Open a terminal window and cd to the FreeSWITCH source dir.

Type this:
sh scripts/freeswitch-gcore > core.trace 

Attach the resulting file, named core.trace, to a JIRA ticket (see Reporting_Bugs#Reporting_A_Bug_With_JIRA)

Collection Information With Valgrind (Linux/Unix)

Valgrind is a debugging tool that helps identify memory usage issues, such as memory leaks.
To run FreeSWITCH in valgrind please follow these steps at the Linux command line:

cd /usr/src/freeswitch.trunk
ulimit -s 240
valgrind --tool=memcheck --log-file-exactly=vg.log --leak-check=full --leak-resolution=high --show-reachable=yes .libs/freeswitch -vg

FreeSWITCH will start in valgrind. You will probably notice that things move more slowly - this is normal. Please wait for FreeSWITCH to exhibit the behavior being studied - including a core dump if that is what is being investigated.

Once the behavior has been exhibited, stop FreeSWITCH (unless it has crashed) and then look for a file named vg.log in your source directory. This file should be attached to the JIRA issue. Please do not try to interpret the contents of the vg.log file. Leave that to the developers as they are eminently qualified to do so. After sending the vg.log to JIRA please notify the developers and wait for further instructions.

Reporting A Bug With JIRA

If one of the developers requests that you submit a bug report then you will need to log on to jira. You will also need to register and get a username and password.

Where And How To File Bug Reports

The JIRA issue tracking system is laid out in sections called "projects." Following are some helpful guidelines to get you up and running quickly.

NOTE: It is absolutely essential that you include specific, detailed instructions on how to reproduce the issue that you are reporting. Attach copies of any config files, dialplan entries, scripts, etc. that are necessary to replicate the issue. Failing to include this necessary information will result in the JIRA being closed.

Examples Of Well-Written JIRA Submissions

All of these examples are from community member John Wehle, who does a great job of submitting bug reports and patches. All of his submissions can be viewed here. If you

Project

FreeSWITCH is modular in nature, which means that it is broken down into various sub-projects. When you see "project" in JIRA, think "sub-project." Related projects are grouped together in categories. The are quite a few projects listed in JIRA so you will have to make an educated guess as to where your issue should be assigned. If you are really at a loss then ask one of the developers or power users for some guidance. Here is a brief look at the most commonly used projects in JIRA:

Category: FreeSWITCH

There are two projects in this category:

  • FreeSWITCH-Buildsystem - Issues relating to compiling, make files, etc.
  • FreeSWITCH-Core - Issues relating to the FreeSWITCH core

Category: Libraries

There are a number of external libraries associated with FreeSWITCH. Occasionally there will be issues with these libraries and it is appropriate to file bug reports under these projects. A few of the more common libraries are:

  • APR - Issues relating to Apache Portable Runtime, a library that helps with cross-platform development
  • Codec Libraries - Issues relating to specific (but external) codec libraries (see also "codecs" under "Modules" below)
  • sofia-sip - Issues related to the Sofia SIP stack

Category: Modules

Modules are the pieces of FreeSWITCH built by the development team and the community. The module category includes these projects:

  • Applications - Issues related to FreeSWITCH applications, e.g. dialplan apps, APIs, etc.
  • codecs - Issues related to the specific FreeSWITCH interfaces to the various codecs, e.g. mod_celt, mod_siren
  • endpoint modules - Issues related to endpoints, e.g. mod_sofia
  • formats - Issues related to file formats, e.g. WAV, mp3, etc.
  • languages - Issues related to built-in scripting languages, like Lua, JavaScript, Perl, etc.
  • XML Interfacing - Issues related to the XML interfaces (xml_curl, xml_cdr, xml_rpc)

Category: Project System

The "project system" category is for items that are related to the FreeSWITCH community rather than the actual software:

  • JIRA - Issues related to JIRA itself
  • Mailing Lists - Issues related to the mailing lists (see lists.freeswitch.org)
  • Repository - Issues related to the Git repository (fisheye.freeswitch.org)
  • Website - Issues related to the main FreeSWITCH website (www.freeswitch.org)
  • Wiki - Issues related to the community documentation site (wiki.freeswitch.org)

Other Projects

There are several other projects that relate to FreeSWITCH that do not belong to any specific category:

  • ASR/TTS - Issues related to speech recognition and text-to-speech
  • Bounty - Issues or bounty requests
  • Event handler modules - Issues related to modules that handle event socket events (e.g. mod_erlang_event)
  • Event Socket Lib - Issues related to the ESL, event socket library, which is used by fs_cli.
  • FS Scripts - Issues related to the accompanying scripts, e.g. fs.pl
  • Janitorial Projects - Issues related to various janitorial projects
  • OpenZAP - Issues related to the OpenZAP TDM abstraction library, i.e. issues with tradition telephony
  • TCAPI - Issues related to the external TCAPI project (www.tcapi.org)

Type

You specify the type of issue you are opening:

  • Bug - Use this if you have a bug that needs to be fixed
  • New Feature - Use this to suggest a new feature
  • Task - Less commonly used, however tasks can be assigned and tracked as well
  • Improvement - Similar to new feature but instead this is to suggestion a way to improve an existing feature

Summary

Type in a brief but descriptive summary here. This text appears in various places in the JIRA system.

Priority

Please select the priority. NOTE: just because you feel passionately about your issue it does not necessarily mean that it is a high priority item! Please be accurate in selecting the priority level. The developers will address all issues, regardless of priority level.

  • Trivial - The lowest priority level, can also be used for really easy fixes
  • Minor - A low priority level, used for annoying bugs that don't actually break anything
  • Patch - Use this priority if you are submitting a patch
  • Major - For serious issues that can affect production deployments use this priority
  • Critical - Very high priority, usually reserved for issues that cause crashes
  • Stopper - Highest priority, used for things that prevent FreeSWITCH from working at all

Assignee

The assignee is "in charge" of the issue. Assign to yourself or leave at "automatic" unless one of the developers tells you otherwise.

Reporter

The reporter is the person who is submitting the JIRA issue; defaults to your JIRA username, which is what you want.

Environment

Specify the environment in which you are testing the issue. Is there any special hardware?
NOTE: Those in a Linux/Unix environment will need to specify several other things. (See the several items below after "Platform")

Description

Provide a detailed description of the symptoms you are experiencing or a description of the new feature or improvement you are suggesting. When reporting a bug, please describe the symptoms and not a diagnosis. Please note what is actually happening versus what you believe should be happening.
Please do not paste more than 30 lines of text into the description.
Attach config files, debug traces and backtraces as separate files. (See below.)
Alternatively, paste in a link to a pastebin entry.

Original Estimate

Estimate the amount of time to fix the issue. If you aren't sure then make an educated guess.

Attachment

Use the attachment button to attach text files to this issue. Please attach configuration files, screen captures of CLI debug output, backtraces, etc. here.

Platform

Select your operating system and CPU combination from the drop-down box.

Uname

Linux/Unix users please supply the output of this command:

uname -a

Windows users please put "N/A"

CPU Info

Linux/Unix users please supply the output of this command:

cat /proc/cpuinfo

Windows users please put "N/A"

GCC Version

Please note your version of the gcc compiler. Use command:

gcc --version

Windows users please put "N/A"

Git Rev

Please note the Git revision level. At the FreeSWITCH command line press F12 or type version

Reproduced With Git?

Please verify that the issue is occurring with the latest Git revision. The simplest way to do this is to do a "make current" in the FreeSWITCH source directory.
Windows users please use your Git client (e.g. TortoiseGit) and update to the latest Git revision and then rebuild the project.
If you are able to reproduce the issue on the latest revision then please go ahead and file your bug report.

Recommended way on how to collect info for submission

  • Submit your DialPlan
  • Submit a log from your FreeSWITCH by turning on the following
    • console loglevel 7
    • fsctl loglevel debug
    • sofia profile <profile_name> siptrace on
    • sofia loglevel all 9
  • If you had a segmentation fault collect and submit the backtrace from the coredump file.
  • (Optional) Submit a debug from ngrep or Wireshark by

1) Run either command

  • ngrep -qt -W byline port <sip port> -O filename.pcap --or--
  • tshark -S -w filename.pcap port <sip port>

2) Provide a way to filter the call that contains a bug; for instance,
sip.Call-ID=="<Call-ID>"

Configuring Your System For Remote Access

Occasionally there are extreme, curious, and downright weird scenarios that the developers must "see for themselves," so it is nice for them to have direct access to your FreeSWITCH server in these cases. Here's a checklist of things to consider:

  • Public IP address
  • Firewall issues
  • Your company's IT security policy
  • SSH server, ssh keys

The absolute easiest way for the developers to access your system is via direct ssh connection. (If you do not have a public IP address on your system then there is a second option: ssh tunnel command; see below.)

Linux Prerequisites

On Linux systems please do this:

cd /path/to/freeswitch/source
make support
./support-d/prereq.sh

These will install the necessary prerequisites for the developers to log in and work on your system.

SSH Tunnel Command For Linux Systems Without Public IP

If your system is behind a firewall and NAT then it will require an alternate means of giving remote access to the developers. The prerequisites are still applicable, so definitely get those in place.

To do the ssh tunnel command, go to the command prompt:

ssh -N -p222 -R xxxxx:127.0.0.1:22 guest@yoda.ostag.org

In this case, xxxxx is the TCP port number. Please ask a developer to suggest a port number for you so that there isn't a collision with an existing port. If this is the first time connecting you will need to accept the RSH key by typing 'yes' at the prompt. At this point the developer will tell you what to do next.

See Also