FreeSWITCH          




FreeSWITCH
Page tree
ConfigureSpace tools
Skip to end of metadata
Go to start of metadata

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

 Click here to expand Table of Contents

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

Recommended Submissions

  • Submit your DialPlan
  • Submit a log from your FreeSWITCH by turning on the following
    • change logfile.conf.xml

      • update from

      • to

    • 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
  • 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 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.

Open a JIRA Ticket

If one of the developers requests that you submit a bug report then you will need to log on to JIRA with your username and password, then open a JIRA ticket.

Click the Create button at the top of the page. This will bring up the "Create Issue" form dialog to be completed as directed below.

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.

Project

Select the overall category under which your ticket falls by typing a few characters or opening the dropdown listbox. Here are some popular projects:

Issue Type

Specify the type of ticket you are opening:

  • Bug - Use this if you have a bug that needs to be repaired
  • New Feature - Use this to suggest a new feature
  • Task - Rarely used, however tasks can be assigned and tracked as well
  • Improvement - Similar to new feature but instead this is to suggest 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 to identify this ticket.

Component

The JIRA issue tracking system is laid out in sections called "projects." FreeSWITCH is modular in nature, which means that it is broken down into various sub-projects. When you see "Component" in JIRA, think "sub-project." Related projects are grouped together in components. There are quite a few components 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.

Type the first few characters to search incrementally or use the dropdown listbox to see all components. Here is a brief look at the most commonly used components in JIRA:

  • Bounty - to offer a monetary donation for a new feature or improvement
  • Build System - Issues relating to compiling, make files, etc.
  • FreeSWITCH-Core - Issues relating to the FreeSWITCH core engine
  • Sound Files - issues relating to the supplied sound prompts
  • mod_ - a module name (which begins with mod_ )

Affects Versions

Select all FreeSWITCH™ versions on which you have reproduced this issue. Note that the developers will ask you to test on the latest Master to see if the issue still exists.

Environment

Specify the environment as it affects this issue. Is there any special hardware? Are you using special drivers or kernel options?
NOTE: Those in a Linux/Unix environment will need to specify additional information. (See the items below after "Platform")

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.)

Attachment

Use the Browse... button 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.

CPU Architecture

Select the CPU family running FreeSWITCH™.

CPU Info

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

sed '/^$/!H;/^$/x;$!d' /proc/cpuinfo

Windows users please put "N/A"

Kernel

Select the kernel(s) on which you tested this issue.

Uname

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

uname -a

Windows users please put "N/A"

Userland

Select the userland(s) on which you're testing this issue.

Distribution

Select the operating system distribution on which you are testing this issue.

Distribution Version

Select the version(s) of operating system on which you are testing this issue.

LSB Release

Paste the output of "lsb_release -a" into this textbox.

Compiler Type

Select the compiler that you used to create the build with this issue.

Compiler Version

Paste the output of "gcc --version" or your compiler of choice into the textbox.

FreeSWITCH Version

The exact git commit hash that exhibits this issue. Paste the output of the fs_cli "version" command into this textbox.

Git MASTER Version

Paste here the exact version hash of the latest GIT HEAD (MASTER) version as of this second that reproduces your issue.

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://freeswitch.org/jira - JIRA trouble ticket tracking system