TrueNAS Nightly Development Documentation
This 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.

Last Modified 2024-11-15 16:32 EST

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.

Auditing Event Types

Session and User Auditing Events

Authentication Events

Audit message generated every time a client logs into the TrueNAS UI or an SSH session or makes changes to user credentials.

Method Call Events

Audit message generated every time the currently logged in user creates a new user account or changes user credentials.

Sudo Accept or Reject Events

Generated every time a user logged in to a shell session uses sudo to perform a command as root or is denied sudo permission. The event data for a sudo event includes the command.

SMB Auditing Events

SMB events are omitted by default from the System > Audit screen. To view SMB audit results, go to System > Services and click 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.

Connect Events

Generated every time an SMB client performs an SMB tree connection (TCON) to a given share. Each session can have zero or more TCONs.

Disconnect Events

Generated every time an SMB client performs an SMB tree disconnect to a given share.

Create Events

Generated every time an SMB client performs an SMB create operation on a given tree connection (TCON). Does not log internally-initiated create operations. Each SMB tree connection can have multiple open files.

Read or Write Events

Generated at configurable intervals as an SMB client reads from or writes to a file. Specifies the minimum amount of time to wait before generating another read or write event for a given file type.

For example, when set to 5 and an SMB client does constant writes to a file, only 12 events are generated per minute. The default value is 60, or one event per type per minute. File-based counters are printed within close messages, and connection-based counters are included in disconnect messages.

Read or Write Offload Events

Generated at configurable intervals as an SMB client performs offloads of reads from or writes to a file. Specifies the minimum amount of time to wait before generating another offload read or write event for a given file type.

Open or Close Events

Generated every time an SMB client opens or closes a file. When a file is opened or closed a summary of file system operations performed on the type is included in the audit message.

Rename Events

Generated when a client attempts to rename a file.

Set_Attr Events

Generated when a client attempts to set basic file attributes (for example DOS mode or file timestamps). The key attr_type indicates the precise type of attributes that are changed in the event this message records.

Set_Quota Events

Unlink Events

Generated when a client attempts to delete a file or directory from a share.

Set_ACL Events

Generated when a client attempts to set an NFSv4 ACL on a file system or to grant a user (OWNER) read and write permissions to the file system.

Audit Message Records

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

Message Fields

Each audit message JSON object includes:

Field	Description
aid	GUID uniquely identifying the audit event.
vers	JSON object containing version information of the audit event. Audit version identifiers represent the major and minor versions of the internal TrueNAS audit message. Major versions are not made outside a major TrueNAS release. Minor version changes indicate non-breaking changes to format, such as adding a new optional field. Major version changes can be renaming or removing an existing mandatory field.
time	UTC timestamp indicating when the event occurs.
addr	IPv4 or IPv6 address for the client generating the audit message.
user	Username of either the user or client generating the audit message. If no username, could be the user ID prefixed with UID.
svc	Unique human-readable service identifier (all uppercase alpha characters) for the TrueNAS service generating the audit message (always SMB).
event	Human-readable name for the event type for the audit message. Name is in all uppercase alpha characters that can include an underscore (_) or dot(.) special characters. See Audit Event Types above for more information.
svc_data	A JSON object containing tree connection (TCON) specific data. This is standardized for all events.
event_data	A JSON object containing event-specific data. This varies based on the event type.
sess	GUID unique identifier for the session.
success	Shows true if the operation succeeded or false if it fails.

Accessing Auditing Screens

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

Searching Audit Logs

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 when the syntax is valid and 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 (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.

Configuring SMB Auditing

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.

Configuring Audit Storage and Retention Policies

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.

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:

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.