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.

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 and include the Affects Version fields.

Enter a short, descriptive title that helps developers find the issue and understand the topic in the Summary field.

Enter specific issue details in the Description field.

Select a TrueNAS release from the Affects Version dropdown list. If you cannot locate the version of software installed on the dropdown list, include it in the Description field.

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

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

PS C:\Users\tester> sftp admin@exampletruenas.net
Connected to exampletruenas.net.
sftp> cd /home/admin
sftp> get testdebug.tgz
Fetching /home/admin/testdebug.tgz to testdebug.tgz
/home/admin/testdebug.tgz						100% 7110KB	4.1MB/s	00.01
sftp> exit

Jira provides a public-facing area for files that do not require privacy. If you are not concerned about data privacy, attach the debug, core, log, or other files to the Jira ticket. Debug files attached directly to a Jira issue ticket are visible to other users searching and reading Jira issue tickets.

For users concerned about data privacy, iXsystems provides a link to a secure file attachment ticket where you can upload files with sensitive information like a system debug or screenshot of network connections.

After submitting a bug report, Jira sends a confirmation email with a link to your Jira issue ticket. The Jira issue ticket includes a link to the TrueNAS Private File Attachments area where you can upload the debug file and any other images or logs you kept private. Link the private file upload ticket to your Jira issue report before you save the private upload file ticket.

Only authorized individuals can access files attached to private file upload tickets!

Jira tickets with debugs directly attached are marked private, limiting access to only the ticket creator and authorized iXsystems personnel. Using the private file attachment tickets keeps issue tickets public so others can see the reports and track progress while still protecting private data.

Drag and drop public-facing files into the Attachment box when creating a new ticket:

To protect your privacy, use the link in the system-generated message in your Jira ticket to upload sensitive information to the TrueNAS Private File Attachments area. Link your private upload ticket 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.