Issue Reporting in Jira

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 an Atlassian 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.

  Include a console log if the error is a web interface issue. If unsure how to save these, see the Adding a Debug File to a Report and Web Console Log sections in this article.

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

See https://security.truenas.com/ for security advisories and software bill of materials for specific TrueNAS releases.

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 /var/tmp/fndebug.

The freenas-debug command-line utility collects debugging information.

Debug files contain log files which can include personal information such as usernames, networking configuration, device serial numbers, or other identifying information about your system. Files uploaded to an issue from the System > Support screen using Attach Debug or through the Jira Private File Upload service are only visible to iXsystems engineers. The iXsystems Privacy Policy contains a detailed statement of our commitment to data privacy.

Always store debug files in a secure location. Please review debugs and redact any sensitive information before sharing with external entities. Use a file archiver utility, such as 7-zip, to open compressed debug archives and review log contents.

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.