TrueNAS Nightly Development DocumentationThis content follows experimental nightly development software. Pre-release software is intended for testing purposes only.
Use the Product and Version selectors above to view content specific to a stable software release.
Audit Logs
10 minute read.
TrueNAS 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 > Audit screen lists all session, or user events, facilitating comprehensive monitoring. Logs include who performed the action, timestamp, event type, and a short string of the action performed (event data).
TrueNAS includes a manual page with more information on the VFS auditing functions.
SMB events are omitted by default from the System > Audit screen.
To view SMB audit results, go to System > Services and click receipt_long Audit Logs for the SMB service or use advanced search on the main Audit screen to query
"Service" = "SMB"
.
SMB audit logs include all SMB protocol events, but do not include changes to SMB configuration such as creating an SMB share or querying and modifying SMB ACLs. See the middleware service log to review those 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).
Users have access to audit information from three locations in the TrueNAS UI:
- Credentials > Users details screen through the Audit Logs option
- On the Users screen, 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 screen, click the Configuring SMB Auditing. Edit icon on the desired SMB share row where Enable, watch and ignore settings are available. For details see
- System > Services > SMB to view SMB audit logs
- On the Services screen, click the Audit Screen. 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
- System > Audit option on the main navigation panel
- The default Audit log screen 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.
You might need to stop and restart the SMB service in order to view logged events.
To configure Audit storage and retention settings, click Audit Settings on the Audit screen or go to System > Advanced Settings, 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.
For example, to change the percent usage warning threshold for the storage allocated to the Audit database:
Navigate to System > Advanced screen.
Select the Configure button on the Audit widget.
In the Audit configuration popup, change the value in the Quota Fill Warning field to the desired percentage.
Select the Save button to effect the change.