TrueNAS SCALE Nightly Development Documentation
This content follows experimental early release software. Use the Product and Version selectors above to view content specific to a stable software release.

Audit Logging

9 minute read.

Last Modified 2024-03-15 13:07 EDT

Auditing Overview

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.

Auditing Event Types

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

Session and user auditing events

Authentication Events

Audit message generated every time a client logs into the SCALE 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.

SMB auditing 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 set a user or group quota on an SMB 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 SCALE 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.

System and User Auditing

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.

Accessing Auditing (Screens)

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

Credentials > Local Users details screen through the Audit Logging option
Sharing SMB details screen through the Audit Logging option
System Settings > Audit option on the main navigation panel

Click Audit Logging 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.

Click Audit Logging on the SMB row on the Services screen to open the Audit log screen with the Search field filter added to show only SMB events.

The main System Settings > Audit screen shows 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 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.

Configuring Session Auditing

To configure session auditing 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.
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.
Quota Fill Warning (in %)	Enter a percentage threshold. TrueNAS generates a warning level alert when the dataset quota reaches that capacity used.
Quota Fill Critical (in %)	Enter a percentage threshold. TrueNAS generates a critical level alert when the dataset quota reaches that capacity used.