This article is a guide for putting together a bug report so that it gets addressed as quickly as possible.
First, Kali Linux is a labor of love, born out of a desire to give back to the community, a community that we’re a part of. In our development roles, it’s our goal to continually improve and evolve the project, making things better for the entire community of Kali Linux users. The developers who provide support to you are volunteers doing so out of altruism. Kali Linux is their gift to you. Please keep this in mind when making your comments.
Second, the goal of a successful bug report is to enable the Kali Linux developers to reproduce the issue and see the failure, if any. If the Kali development team can reproduce the reported failure, they can proceed to gather extra information until the root cause is determined. If the failure can’t be reproduced, the development team will request additional information until they can reproduce the results reported by the submitter.
Please note, submissions are best read by our team in English.
Help us help you! To give us the best start in getting your issue resolved:
- Supply all the information you can. Try to stick to what’s relevant, but if you’re uncertain, too much is better than too little.
- Keep your bug report objective and try to stick to the facts at hand.
- Be very clear about what is a fact — document these whenever possible, via logs, scrollback captures, etc. — and what is a hypothesis on your part.
- Do not quote Wikipedia and other non-primary resources as “facts” in your submission. What’s happening on your system is what’s at issue, not what Wikipedia claims
- Do not stack multiple issues into a single report; submit additional reports as needed. One person should submit one report, for one bug, on one particular hardware combination. Trying to stack multiple variations into a single report makes any specific issue in there very difficult to tease out. What seem like similar bugs to you may in fact turn out to be unrelated.
- If one of the developers asks for additional information, please do your best to understand what’s being asked for and provide it in a reasonable time. If you’re not sure you understand what you’re being asked for, ask for clarification, we’ll do our best to provide more guidance. Do not post comments that are unhelpful such as “Me too!” or “+1”.
- Do not complain about how long it takes to fix a bug. Remember: the developers are volunteers with day jobs, which are not fixing your bugs for you.
How to Report a Bug
The Kali Linux Bug Tracker can be found at https://bugs.kali.org. This section will guide you through signing up for a new account, creating a system profile, and creating a detailed bug report for submission to the Bug Tracker.
Signing Up For a Bug Tracker Account
You’ll have to create an account before the Bug Tracker will allow you to submit reports or comment on existing ones.
On the bug tracker website, click Signup for new account.
Provide a username, e-mail address, and respond to the CAPTCHA challenge. Click the Signup button to proceed.
If successful, the next page will notify you that the account registration has been processed and the bug tracker system will send a confirmation email to the address you provided. You will need to visit the link in the email in order to activate your account.
Once your account has been activated, click Proceed to continue to the Bug Tracker login page.
Creating a Profile in the Kali Linux Bug Tracker
Although not required, we recommend you create a unique profile as part of your Bug Tracker account. Profiles are shortcuts that predefine values for your CPU platform, operating system and version, as well as allowing you to provide some additional information, all of which is automatically submitted as part of your bug report. You can create a custom profile for each Kali system you’re using or select from the default profiles provided.
To create or edit a custom profile, select My Account from the main page and then select Profiles. Add the specific information and description for your system and click the Add Profile button when done.
Once the profile has been added, it will appear in the Select Profile drop-down list when you report a new issue. Create as many different profiles as you need, just be sure to select the appropriate one when submitting your bug report, or a lot of confusion may result.
Be Sure You Are Not Duplicating a Previous Report
Before starting your report, search the site for keywords related to your issue. If there is already an existing bug not related to hardware, please do not duplicate the request or add notes that provide no new information or are otherwise unnecessary (e.g. “Me Too” or “+1”). If the bug has already been reported, you can view the status of any progress toward resolving the issue by clicking the ID link.
However, if you believe the issue to be hardware related, please submit a new report with your specific information, even if it appears similar. There is a strong chance that your hardware does not exactly match that of another reporter. Do not assume that just because you have the same desktop or laptop model that your issue is not unique.
Creating the Report
To begin your report, log into your account and click the Report Issue link on the landing page. You will need to provide as much information as you possibly can. If unsure, review the pointers at the beginning of this document.
The following fields are mandatory within the report:
Even though the other fields are not mandatory, we recommend you try to include as much information as possible within each option while paying special attention to the following fields:
- Reproducibility — How reproducible is this bug? Always? Only sometimes? Only under specific circumstances?
- Select Profile — We need to know what you’re running, and what you’re running it on.
- Steps to Reproduce — Be very clear here, and provide as much concrete detail as you can.
- Additional Information
- Upload File (error logs, screenshot)
Decide the Proper Category
There are currently four (4) categories available in the Kali bug tracker. Before you begin your request, ensure it is properly designated for one of the following:
- General Bug
- Kali Package Bug
- New Tool Requests
- Tool Upgrade
Do not request support or ask questions within the bug tracker. Kali Linux offers several options for support including http://docs.kali.org , https://forums.kali.org, and our IRC chat room (#kali-linux on freenode)
Providing a Descriptive Summary
The summary field is essentially the ‘title’ of the bug report and it will be the first thing Kali developers and other visitors see. Provide a short, yet descriptive, summary that describes the issue or request.
A good summary: Chromium Package installed from repo will not run as root user
A bad summary: Chromium doesn’t work
The summary does not need to include everything, but it should convey your reason for submitting the report.
Using dpkg to Find the Package and Version for the Report
You can find which package is installed using a combination of dpkg flags. It is important to include relevant information from the output of these commands in your report. The output can also be placed in a text file and uploaded. (Discussed later within this document.)
- dpkg –search
- dpkg –list
- dpkg –status
root@kali:~# type chromium
chromium is /usr/bin/chromium
root@kali:~# dpkg --search /usr/bin/chromium
root@kali:~# dpkg --list chromium
|/ Err?=(none)/Reinst-required (Status,Err: uppercase=bad)
||/ Name Version Architecture Description
ii chromium 55.0.2883.75-3 amd64 Google open source chromium web
root@kali:~# dpkg --status chromium
Status: install ok installed
Maintainer: Debian Chromium Maintainers <email@example.com>
Building the Description Scenario
This is your opportunity to to help us out and provide a well thought-out description of the problem you’re experiencing. Please provide as many details and facts as possible.
Please ensure you include the following where applicable:
- Exact and complete text of any error messages (screen output or log files)
- Exactly what you typed or what actions you took to produce the issue
- A suggested fix, workaround, or patch if you are able to produce one
- The version of the package having the problem, and any information relating to dependent packages
- The kernel version, shared C library, and any other details that seem appropriate
- The output of the command uname –a
- The output of the command dpkg -s libc6 | grep ^Version
- If applicable, software version — ( i.e. python –V, etc.)
- Details of your hardware
- If you are reporting an issue with a device driver, please provide full details on all hardware in your system — for a complete report on your system install lshw from the repos.
- Add any other details that seems relevant
- Do not worry about the report being “too long” — as long as the information is relevant, include it.
Here’s an example of a good bug report, providing information that the development team can immediately use to reproduce and try to understand the bug:
Maintainer: Debian Chromium Maintainers
I installed the chromium web browser from the Kali Linux repos, using the command ‘apt install chromium’. I launched the program from the Kali menu by selecting Applications/Internet/Chromium Web Browser. Chromium did not launch as expected, instead it provided an error pop-up window.
The error message stated, “Chromium cannot be run as root. Please start Chromium as a normal user. To run as root, you must specify an alternate –user-data-dir for storage of profile information”.
I clicked the Close button to close the pop up window.
uname –a output: Linux kali 4.7.0-kali1-amd64 #1 SMP Debian 4.7.6-1kali1 (2016-10-17) x86_64 GNU/Linux
C Library Version: 2.24-8
The Importance of Reproducibility
The Kali Linux bug tracker allows you to provide the frequency of the issue being reported. If you are submitting a request for a new tool or an upgrade to an existing tool, simply select N/A from the drop down options. If submitting a bug, please provide the appropriate response.
Continuing the example above, by design, Chromium will not launch as root, so you would select ‘always’ from the drop-down menu.
It is extremely important you provide an accurate response. If the Kali developers attempt to reproduce the issue, they need to know the frequency. If the issue happens occasionally but you have marked ‘always’, the issue may be closed prematurely as the developer doing the testing may not experience the issue.
Selecting the Proper Profile
As discussed above, using a custom-defined profile is best for each issue reported. If custom profiles are not created, select the appropriate “standard” profile from the drop-down menu. At the time of this writing, the following options are available.
- armel Kali 1.0
- armhf Kali 1.0
- x64 Kali 1.0
- x86 Kali 1.0
Providing Steps to Reproduce the Issue
Although this may seem redundant when compared with the description section, this section should only include the steps taken to reproduce the issue. Some steps may seem unnecessary, but it is important to ensure you document the process as well as you can. The missing step may be the one that’s key to reproducing the issue.
Here’s an example of a good set of steps for reproducing our example Chromium bug.
- Opened a terminal window by selecting Applications/Accessories/Terminal
- Typed ‘apt install chromium’ in the terminal and hit enter to run the command
- Attempted to run Chromium web browser by selecting Applications/Internet/Chromium Web Browser
Providing Additional Information
In this section, you can provide any additional information you believe is relevant to the issue. If you have a fix or workaround for the issue, please provide it in this section. Again, it is important to stick to the facts and document the steps clearly so the developers can reproduce the issue.
An example of some useful “Additional Information”:
There is a simple fix that is well documented on several forums. I tried it and it fixed the issue for me.
- Using a text editor open /etc/chromium/default
- Add –user-data-dir flag
- i.e. CHROMIUM_FLAGS=”–user-data-dir”
Can this be patched within the repo version of Chromium so adding this flag is not required for future releases?
Uploading Relevant Files
Sometimes it is important to provide information to the development team that can’t easily be typed in as text. This section of the report allows you to add screenshots and log files. Be mindful of the size limitation in place.
You can add a file by clicking the ‘Choose File’ button. This will open the file manager for your system and allow you to select the file you want to attach to your report. Once you have selected the file, click the ‘Open’ button to return to your report and click the ‘Upload File’ button.
Submitting the Report
At this point, you are ready to submit the report. All that is left to do is click the ‘Submit Report’ button. Your report will be submitted and assigned a tracking ID. The report will show up on your ‘My View’ page under ‘Reported by Me’. This will allow you to track the issue to resolution.
Bug reports help the Kali Linux development team see the failure with their own eyes. Since they cannot be with you to experience the problem you’re having, you must provide instructions detailed enough that they can make their own systems fail themselves.
Describe everything in detail, stating the steps taken, what you saw, what you did, as well as the expected outcome.
Attempt to find an issue or fix through research, if at all possible — remember, open source development is a participatory process! If you are able to provide a solution to fix the issue for your system, provide the developers with the same level of detail as you did when reporting the bug. It is important that the developers know exactly what you did, so they can successfully repeat the process. This should not stop you from filing a full explanation of the symptom that caused the unexpected behavior.
Write accurately, be clear, precise, and concise to ensure the developers cannot misinterpret what you are trying to convey.
Be prepared to provide additional information; the developers will not ask if they don’t need the information.
Please be patient with your request, the developers want to fix your issue as much as you do. We love what we do and are proud to continue making Kali Linux the most advanced penetration testing distribution ever, and grateful for the assistance we get from you, our community of users, in doing so.