Skip to main content

Reporting Issues to GitHub

About​

After you performed due diligence to make sure that your configuration is correct and you are confident that you have discovered a bug in FreeSWITCH™, please follow these steps to report a bug to the core development team via JIRA.

While writing this page refer to the outline created by bkw

Use Latest Code​

The core developers require that you can reproduce the bug on the latest Master source code. If you report a bug on an older build, it is possible that it has already been corrected. The project volunteers have limited time available so it is only fair that we not burden them with false bug reports.

Instructions on building from the latest code can be found under the Installation wiki tree.

Collect Information​

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 bug report being closed.

  • Submit your DialPlan
  • Submit a log from your FreeSWITCH by turning on the following
    • change logfile.conf.xml
      • update from 
        <map name="all" value="debug,info,notice,warning,err,crit,alert"/>
        • to
        <map name="all" value="console,debug,info,notice,warning,err,crit,alert"/>
    • reloadxml
    • reload mod_logfile
    • console loglevel 7
    • fsctl loglevel debug
    • sofia global siptrace on
    • sofia loglevel all 9
    • fsctl send_sighup (start a new log before running the scenario, then send when scenario complete)
  • If you had a segmentation fault collect and submit the backtrace from the coredump file.
  • (Optional) Submit a debug from ngrep or Wireshark by running either command:
    • ngrep -qt -W byline port <sip port> -O filename.pcap --or--
    • tshark -S -w filename.pcap port <sip port>
  • Provide a way to filter the call that contains a bug; for instance,
    • sip.Call-ID=="<Call-ID>"

Checklist​

To make life easier for the developers, please gather this information prior to posting questions to the mailing list or submitting bug reports to jira.

Basics​

  • Git revision number (or binary file)
  • Operating System and revision (CentOS 6.2, OSX 10.5, Windows Server 2008 R2, etc.)
  • Hardware information (32 or 64 bit processor, RAM, etc.)
    • On Linux, do these commands and capture the output
sed '/^$/!H;/^$/x;$!d' /proc/cpuinfo
uname -a
  • Did you install the default configuration files? Y/N
  • Have you made any modifications or additions to the default config? Y/N
    • If yes, please post copies of any changes made
  • Can the issue be reproduced? Y/N
    • If not, why? Is it intermittent?
    • If yes, please be prepared to help us reproduce it

Attach Files​

  • Attach logs, config files, core files, etc. to the JIRA ticket
  • Don't use pastebin for JIRA tickets as pastebin expires and the logs and configs will be lost
  • Don't attach .rar or zip Files

Advanced​

  • Are you experiencing a segfault? Y/N
    • Can it consistently be reproduced? Y/N
    • Supply a backtrace (bt and bt full)
  • Are you using a script? Y/N
    • What language? Lua/Perl/JavaScript/Python/.Net/C/C++/Java
    • Post a copy of the script
  • Are you using the event socket? Y/N

Examples Of Well-Written Bug Report Submissions​

Note these are on our old bug platform:

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.

Open a GitHub bug report​

If one of the developers requests that you submit a bug report then you will need to log on to github with your account (if you do not have one you can create one for free). Then open a github bug report here.

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 issue being closed.

Issue Type

Specify the type of ticket you are opening:

  • Bug - Use this if you have a bug that needs to be repaired
  • Feature Requests - Use this to suggest a new feature

The New Issue Report​

In the report will be a default template. Be sure to fill out the information it asks for. It is also best to try and note the following items in your bug report (if they have any chance of being applicable).

  • Component - freeswitch is broken down into various modules like mod_spandsp or mod_perl, try to identify which the issue may be related to for it to be assigned to the right user faster
  • Version - Please test with master (and please paste in the ticket the exact version hash of the head you tested against) but if you have found it is broken in other versions too you may also note them.
  • Environment - Specify the environment as it affects this issue. Is there any special hardware? Are you using special drivers or kernel options? What operating system and version are you using. How did you install freeswitch? CPU information (ie: sed '/^$/!H;/^$/x;$!d' /proc/cpuinfo). LSB release too: lsb_release -a. Finally the version freeswtich reports: `fs_cli "version"`

Description​

Provide a detailed description of how to reproduce the symptoms you are experiencing or a description of the new feature or improvement that 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 box.
Attach logs, config files, debug traces, and backtraces as separate files. (See below.)

Attachments​

Click the attach files area at the bottom of the issue page to attach text files to this issue. Please attach logs, configuration files, screen captures of CLI debug output, backtraces, etc. here. Do not use pastebin for JIRA tickets as pastebin entries expire after a time.

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.

See Also​

https://github.com/signalwire/freeswitch - GitHub trouble ticket tracking system