Issue Reporting in Jira
6 minute read.Last Modified 2023-11-16 14:55 EST
We encourage all users to help us make TrueNAS the best NAS by reporting issues, requesting potentially helpful features, and relaying security vulnerabilities.
iXsystems uses Jira to track bugs and develop features. You can view public issues without logging in, but you must create a Jira account to report bugs or suggest features.
Go to the TrueNAS project on Jira and click Create in the top bar.
Set the Issue Type to Bug. The form reloads with more fields. Do not select the Defect option which is only for internal use.
Developers use most of the fields on bug tickets, but you should fill out the Summary and Description to provide a usable report.
The Summary is a short, descriptive title that helps developers find the issue and understand the topic.
The Description lets you enter specific issue details.
A good bug report includes these elements:
A brief, specific, description detailing the problem you encountered.
The steps to reproduce the issue. A simple list of the steps you took to see the issue is fine.
An explanation of what should have happened while taking the steps listed above.
A description of what actually happened while taking the steps listed above.
The TrueNAS software version you are using, which is found on the main Dashboard.
The current service configuration if the bug is service-related to help developers replicate your system.
Any additional details you think can help the developer investigate.
In addition to the above information, please also provide:
A TrueNAS debug file. This is required to help developers identify and troubleshoot issues on your system.
The core file if your system produces a core file error. Save the file and attach it to your ticket.
Screenshots if the bug is a web interface glitch or a formatting problem.
A video if screenshots do not adequately show the issue.
When finished filling out the all fields (i.e., Summary, Description, Affects Version, etc.), click Create at the bottom of the form.
Developers review and update the ticket if/when they need additional information. The Jira account receives emails about the ticket status. Developers might request more details as they work to resolve the issue, so check the ticket periodically.
Want to see a new feature added to TrueNAS? You can see and vote for community-proposed features in the TrueNAS Jira project and make your feature suggestions here. If you find a suggestion that you want to see implemented, open that ticket and click Vote for this issue in the People section.
To suggest a new feature, go to https://ixsystems.atlassian.net/projects/NAS/, log in to your Jira account, and click Create.
Briefly describe the new feature you would like to see added in the Summary section. After creating your feature suggestion, it moves to the Gathering Interest stage, where the community can review and vote for the feature. After gathering enough interest, the TrueNAS Release Council reviews the suggestion for feasibility and determines where to add the feature in the software roadmap.
We publish previous security reports at https://security.truenas.com/.
Security issues do not appear on public issue trackers due to their sensitive nature. If you have discovered a suspected security vulnerability in the latest version of a software release, you can report this directly to the Security Team.
The TrueNAS web interface lets users save debugging information to a text file.
On TrueNAS CORE systems, go to System > Advanced and click SAVE DEBUG.
Click PROCEED to generate the debug file (might take a few minutes).
After generating the debug file, TrueNAS prompts you to download it to your local system and saves a copy in
freenas-debug command-line utility collects debugging information.
On TrueNAS SCALE systems, go to System Settings > Advanced, then click Save Debug and wait for the file to download to your local system. Generating the debug file might take a few minutes to complete. After that, it downloads to your system.
Jira provides a public-facing area for files that do not require privacy. iXsystems also provides a secure file attachment area that only developers can access, where you can upload files with sensitive information like a system debug or screenshot of network connections.
Debug files attached directly to the Jira issue ticket are visible to other users searching and reading Jira issue tickets. To keep your sensitive information private, use the link in the system-generated message posted to your Jira ticket to upload files to the private attachment area. Be sure to link your file uploads to your Jira ticket number before you click Save after uploading your file.
If you are not concerned about data privacy, you can attach the debug, core, log, or other files to the Jira ticket.
Drag and drop public-facing files into the Attachment box when creating a new ticket:
To protect your privacy, please use the link in the system-generated message to upload your debug or any screenshot with sensitive information to the private file attachment area. Link this upload to your Jira issue ticket so developers can locate the file. Files uploaded to this service are only visible to project developers.
For public facing files, open the ticket in your browser and either click Attach, at the top of the ticket, or click the +, in the Attachments section, to open a local system file browser to select the files. You can also drag and drop the file onto the Attachments box and add any comments about it.
Upload private files to our secure private upload service located at https://ixsystems.atlassian.net/servicedesk/customer/portal/15/group/37/create/153. Files uploaded to this service are only visible to project developers.
Web console logs help diagnose problems with the user interface. You can add logs to TrueNAS issues for debugging.
Open the web console by clicking (Menu) > More Tools > Web Developer Tools (Ctrl-Shift-I).
In the upper right, set Persist Logs. Click (More) > Settings. In the Web Console section, set Enable timestamps.
Select the Console tab, then click (Settings) and set Show Timestamps and Persist Logs.
Leave the console open and perform the action that encounters problems.
Right-click in the console window and select Export Visible Messages To > Clipboard.
Open an editor, paste the clipboard contents, and save to a new
After saving the file, open the console with (Menu) > More Tools > Web Developer Tools (Ctrl-Shift-I) and unset Persist Logs.
Open the console by clicking (Options) > More Tools > Developer tools (Ctrl-Shift-I).
Click (Preferences) and select Preserve log and Show timestamps. Close the Preferences window.
Leave the console open and perform the action that encounters problems. Right-click the console window. Choose Save as and save the file.
After saving the file, open the console with (Options) > More Tools > Developer tools (Ctrl-Shift-I) and select Preserve log to clear the checkbox.