Audit Logs

TrueNAS SCALE auditing and logs provide a trail of all actions performed by a session, user, or service (SMB, middleware).

The audit function backends are both the syslog and the Samba debug library. Syslog sends audit messages via explicit syslog call with configurable priority (WARNING is the default) and facility (for example, USER). The default is syslog sent audit messages. Debug sends audit messages from the Samba debug library and these messages have a configurable severity (WARNING, NOTICE, or INFO).

The System Settings > Audit screen lists all session, user, or SMB events. Logs include who performed the action, timestamp, event type, and a short string of the action performed (event data).

SCALE includes a manual page with more information on the VFS auditing functions. Administrative users can enter man vfs_truenas_audit in a SCALE command prompt to view the embedded manual page.

Events are organized by session and user, and SMB auditing.

Session and user auditing events

SMB auditing events

Audit records contain information that establishes:

• Type of event
• When the event occurred (timestamp)
• Where the event occurred (source and destination addresses)
• Source of the event (user or process)
• Outcome of the event (success or failure)
• Identity of any individual or file names associated with the event

Each audit message is a single JSON file containing mandatory fields. It can also include additional optional records. Message size is limited to not exceed 1024 bytes for maximum portability with different syslog implementations.

Use the Export to CSV button on an audit screen to download audit logs in a format readable in a spreadsheet program. Use the Copy to Clipboard option on the Event Data widget to copy the selected audit message event record to a text or JSON object file. The JSON object for an audit message contains the version information, the service which is the name of the SMB share, a session ID and the tree connection (tcon_id).

Authentication and other events are captured by the TrueNAS audit logging functions. The TrueNAS SCALE auditing logs event data varies based on the type of event tracked.

Users have access to audit information from three locations in the SCALE UI:

• Credentials > Local Users details screen through the Audit Logs option
  • On the Local Users page, click Audit Logs on the Users details screen to open the Audit log screen with the Search field filtered to show events (authentication, changes to existing users, creating new users, etc.) specific to that user. For more details see Audit Screen.
• Shares > Window (SMB) Shares details screen through the share edit Audit Logging option
  • On the Sharing page, click the edit Edit icon on the desired SMB share row where Enable, watch and ignore settings are available. For details see Configuring SMB Auditing.
• System > Services > SMB to view SMB audit logs
  • On the Services page, click the receipt_long Audit Logs icon on the SMB row. This opens the main Audit log page with the Search field filter configured to show only SMB events. For details see Audit Screen.
• System Settings > Audit option on the main navigation panel
  • The default Audit log page is unfiltered and displays all system events such as authentication and SMB events.

The audit screen includes basic and advanced search options. Click Switch to Basic to change to the basic search function or click Switch to Advanced to show the advanced search operators.

You can enter any filters in the basic Search field to show events matching the entry.

To enter advanced search parameters, use the format displayed in the field, for example, Service = “SMB” AND Event = “CLOSE” to show closed SMB events. Event types are listed in Auditing Event Types.

Advanced search uses a syntax similar to SQL/JQL and allows several custom variables for filtering. Parentheses define query priority. Clicking the advanced Search field prompts you with a dropdown of available event types, options, and operators to help you complete the search string.

For example, to search for any SMB connect or close event from the user smbuser or any non-authentication SMB events, enter (Service = "SMB" AND Event in ("Connect", "Close") AND User in ("smbuser")) OR (Event != "Authentication" AND Service = "SMB").

The advanced search automatically checks syntax and shows done when the syntax is valid and warning for invalid syntax.

Click on a row to show details of that event in the Metadata and Event Data widgets.

Export as CSV sends the event log data to a csv file you can open in a spreadsheet program (i.e., MS Excel, Google Sheets, etc.) or other data management app that accept CSV files.

The assignment (Copy to Clipboard) icon shows two options, Copy Text and Copy Json. Copy Text copies the event to a text file. Copy Json copies the event to a JSON object.

Configure and enable SMB auditing for an SMB share at creation or when modifying an existing share.

SMB auditing is only supported for SMB2 (or newer) protocol-negotiated SMB sessions. SMB1 connections to shares with auditing enabled are rejected.

From the Add SMB Share or Edit SMB Share screen, click Advanced Options and scroll down to Audit Logging.

Selecting Enable turns auditing on for the share you are creating or editing.

Use the Watch List and Ignore List functions to add audit logging groups to include or exclude. Click in Watch List to see a list of user groups on the system. Click on a group to add it to the list and record events generated by user accounts that are members of the group. Leave Watch List blank to include all groups, otherwise auditing is restricted to only the groups added.

Click in Ignore List to see a list of user groups on the system.. Click on a group to add it to the list and explicitly avoid recording any events generated by user accounts that are members of this group.

The Watch List takes precedence over the Ignore List when using both lists.

Click Save.

To configure Audit storage and retention settings, go to System Settings > Advanced, then click Configure on the Audit widget.

The Audit configuration screen sets the retention period, reservation size, quota size and percentage of used space in the audit dataset that triggers warning and critical alerts.

Audit Settings

Settings	Description
Retention (in days)	Enter the number of days to retain local audit messages.
Reservation (in GiB)	Enter the size (in GiB) of reserved space to allocate on the ZFS dataset where the audit databases are stored. The reservation specifies the minimum amount of space guaranteed to the dataset, and counts against the space available for other datasets in the zpool where the audit dataset is located. To disable, enter zero (0).
Quota (in GiB)	Enter the size (in GiB) of the maximum amount of space that can be consumed by the dataset where the audit databases are stored. To disable, enter zero (0).
Quota Fill Warning (in %)	Enter a percentage threshold. TrueNAS generates a warning level alert when the dataset quota reaches that capacity used. Allowed range: 5 - 80.
Quota Fill Critical (in %)	Enter a percentage threshold. TrueNAS generates a critical level alert when the dataset quota reaches that capacity used. Allowed range: 50 - 95.

For example, to change the percent usage warning threshold for the storage allocated to the Audit database:

1. Navigate to System > Advanced page.
2. Select the Configure button on the Audit widget.
3. In the Audit configuration popup, change the value in the Quota Fill Warning field to the desired percentage.
4. Select the Save button to effect the change.