(408) 943-4100                     V   Commercial Support Toggle between Light and Dark mode

Issue Reporting

  5 minute read.

Last Modified 2021-10-08 14:53 EDT

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.

TrueNAS Jira Project

Bug Reports

Go to the TrueNAS project on Jira and click Create in the top bar.

Create Ticket

Set the Issue Type to Bug. The form will reload with more fields. Developers use most of them, but you should fill out the Summary and Description to provide a useable 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.

JiraSummaryDescription

A good bug report includes these elements:

  • A “to the point” description detailing the problem you encountered.

  • Steps to reproduce the issue. A simple list of the steps you took to see the issue is fine.

  • An explaination of what should have happened while taking the steps listed above.

  • A description of what actually happened while taking the steps listed above.

  • Your TrueNAS software version (found in Dashboard).

  • If the bug is service-related, include the current service configuration to help developers replicate your system.

  • Always include a TrueNAS Debug file. Include a console log if the error is a web interface issue. If unsure how to save these, refer to the TrueNAS Debug and Web Console Log tabs on this page.

  • Include screenshots if the bug is a web interface glitch or a formatting problem.

  • Include a video if screenshots do not adequately show the issue.

  • Include additional details you think can help the developer investigate.

When finished filling out the Description, click Create at the bottom of the form.

Submit Ticket

Developers will review and update the ticket if/when they need additional information. The Jira account receives emails about the ticket status. Developers may request more details as they work to resolve the issue, so check the ticket periodically.

Feature Suggestions

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. To see the list of community-proposed features, go to the TrueNAS Jira project and search for open suggestions. If you find a suggestion that you want to see implemented, open that ticket and click Vote for this issue in the People section.

JiraSuggestionVote

To suggest a new feature, go to https://jira.ixsystems.com/projects/NAS/, log in to your Jira account, and click Create.

JiraSuggestionCreate

Enter a brief Summary and describe the new feature you’d like to see added to the software. After creating your feature suggestion, it will move to the Gathering Interest stage, where the community can review and vote for the feature. After gathering enough interest, the TrueNAS Release Council will review the suggestion for feasibility and find where to add the feature in the software roadmap.

Security Issues

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.

Creating a Debug File

The TrueNAS web interface lets users save debugging information to a text file.

Go to System > Advanced (System Settings > Advanced in TrueNAS SCALE) and click SAVE DEBUG. Click PROCEED to generate the debug file. You can’t click options in the web interface while generating the debug file. A dialogue box shows debug file creation progress.

After generating the debug file, TrueNAS will prompt you to save it to your local system (e.g. Downloads), or it will automatically download to your specified downloaded files location.

Debugging information is collected by the freenas-debug command-line utility. A copy of the information is saved to /var/tmp/fndebug.

Adding a Debug File to a Report

Jira provides a secure area for uploading files with sensitive information like a system debug.

New Tickets

Drag and drop the file into the Private Attachment box:

JiraAttachmentNew

Clicking browse opens a local system file browser for selecting files.

Existing Tickets

Open the ticket in your browser and find the Attachments section.

JiraAttachmentExisting

Click the + to open a dialog for adding a new file to the secure area.

JiraNASAttachPrivateDialog

Drag and drop the file, add any comments about it, then click Attach.

Uploads in the Private section are only visible to project developers. JIRA removes them when closing the ticket.

Web Console Log

Web console logs help diagnose problems with the user interface. You can add logs to TrueNAS issues for debugging.

Firefox

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 console.log file.

After saving the file, open the console with (Menu) > More Tools > Web Developer Tools (Ctrl-Shift-I) and unset Persist Logs.

Chrome

Open the console by clicking (Options) > More Tools > Developer tools (Ctrl-Shift-I).

Click (Preferences) and set 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 unset Preserve log.

Attaching a Console Log File to a Report

Go to the iXsystems Bug Tracker. Locate an existing ticket or create a new one reporting the problem. Attach the console log file to the ticket by dragging it to Attachments.