Skip to main content
Version: 3024.10

Audit Logging

Audit logs track and record events on a share as they occur, ranging from high-level user activities, such as file access and lookups, to detailed system-level actions, including basic read and write operations.

When audit logging is enabled, you can specify the level of detail to control which events are recorded for each share, in order to meet your monitoring and security needs.

Audit Levels​

Audit levels are incremental, with each higher level including all events from lower levels. Below are the events logged at each level:

Audit Level 1:

  • Create:
    • SMB2 CREATE
    • SMB2 SET_INFO (creating a hard link to an existing file)
  • Delete:
    • SMB2 CREATE (with CreateOptions DELETE_ON_CLOSE) + SMB2 CLOSE
    • SMB2 SET_INFO (SMB2_0_INFO_FILE)
  • Rename:
    • SMB2 SET_INFO
  • Modify permissions:
    • SMB2 SET_INFO (SMB2_0_INFO_SECURITY)
    • SMB2 CREATE
  • Auth-related operations:
    • Logs all actions from start to end of SMB2SESSION_SETUP, which determines whether the client can successfully access SMB2 services.
    • SMB2 LOGOFF
    • SMB2_CLOSE

Audit Level 2:

  • Write:
    • SMB2 WRITE
    • SMB2 SET_INFO
    • SMB2 IOCTL
  • Update:
    • SMB2 FLUSH

Audit Level 3:

  • Read access permissions:
    • SMB2 QUERY_INFO (INFO_FILE & INFO SECURITY)
  • Lookup:
    • SMB2 QUERY_DIRECTORY (can use a wildcard, pattern, or an exact file name).
      note

      File lookup can also be performed by sending a SMB2 CREATE request with the file name and CreateDisposition set to 1 (Open if exists or fail). However, this action will be logged as a CREATE event.

  • Readlink:
    • Same as SMB2 CREATE
  • Readdir:
    • SMB2 QUERY_DIRECTORY (can use a wildcard, pattern, or an exact file name).

Audit Level 4:

  • Read:
    • SMB2 READ
  • Commits:
    • SMB2 FLUSH

Audit Level 5:

  • Stat:
    • Although SMB2 does not have a specific stat request, this audit level logs events that result in a stat() system call such as SMB2 QUERY_INFO or SMB2 QUERY_DIRECTORY.
  • Commits:
    • SMB2 FLUSH
  • SMB2 IOCTL COPYCHUNK
  • Share root open

Configuring Audit Logging​

This section outlines the three factors involved in configuring audit logging:

  • Audit Logging Enabled/Disabled: A global setting that toggles audit logging feature across the system.
  • Output Parameters: A global setting that defines where the audit logs are stored and how they are formatted.
  • Audit Level: A per-share setting that determines the level of detail logged for each share.
Global Parameter Enabling/Disabling Audit Logging

Value Type: boolean

Value Format: true|false

  • true: Enables audit logging.
  • false: Disables audit logging.

Default Value: false

Global Parameter Configuring Audit Log Output

Value Type: string

Value Format: path=<path>[,days=<days>][,uid=<uid>][,gid=<gid>][,cn=<cn>][,sensitive_data=<sensitive_data>]

  • path=<path>: (required) Specifies the directory where audit log files are stored. Each audit log file ends with a suffix with the date it pertains to.
  • days=<days>: (optional) Specifies how many days audit log files are retained. Default value: 1.
  • uid=<uid>: (optional) Specifies whether log messages include the POSIX user ID of the authenticated user whose actions are being logged. Possible values:
    • true: Include the POSIX user ID in log messages.
    • false: Do not include the POSIX user ID in log messages. Default value: true.
  • gid=<gid>: (optional) Whether log messages include the POSIX group ID of the authenticated user whose action is being logged. Possible values:
    • true: Include the POSIX group ID in log messages.
    • false: Do not include the POSIX group ID in log messages Default value: true.
  • cn=<cn>: (optional) Specifies whether log messages include the common name of the authenticated user whose action is being logged. Possible values:
    • true: Include the common name in log messages.
    • false: Do not include the common name in log messages Default value: true.
  • sensitive_data=<sensitive_data>: (optional) Defines how sensitive data is handled in log messages. Sensitive data includes domain names, IP addresses, user names and IDs, and file paths. Possible values:
    • allow: All data is displayed as-is.
    • strip: Sensitive data is stripped, and replaced with ***.
    • hash: Sensitive data is hashed, allowing for differentiation between different sensitive data appearances (e.g., distinguishing one IP address from another), without revealing the original values.
      Default value: allow.

Default Value: none

Examples:

  • path=/var/log/tsmb-audit,days=1,uid=true sets the path to /var/log/tsmb-audit, retains the audit log files for 1 day, and includes the POSIX user ID in log messages.
Share Parameter Setting Audit Level for a Share

Value Type: integer

Default Value: none

Examples:

  • 1 sets the audit level to 1 for the share.
  • 3 sets the audit level to 3 for the share.

Enabling Audit Logging and Configuring the Output Parameters​

To enable audit logging and configure the output parameters, set the audit_enable and audit_params parameters in the configuration file. For example:

[global]
. . .
audit_enable = true
audit_params = path=/var/log/tsmb-audit,days=1,uid=true
. . .
[/global]

Setting the Audit Level on a Share Using the Configuration File​

Once audit logging has been enabled and configured, edit the relevant [share] section of the configuration file, set the audit_level parameter to the desired value, as shown below:

[share]
netname = MyShare
path = /export/share
audit_level = 3
[/share]

Adding a Share with an Audit Level Using the CLI​

Once audit logging has been enabled and configured, specify the audit level using the -A or --audit-level parameter. For example:

sudo tsmb-cfg share add -n MyShare -p /export/share -A 3