Skip to main content

Audit Logging

Audit logging allows you to track and record events occurring on a share. These events can range from high-level user activities, such as file access and lookups, to more detailed system-level actions, including basic read and write operations.

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

Audit Levels​

Audit levels are incremental, meaning each higher level includes all the information from the lower levels. The following outlines the events logged at each level:

  1. 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
  2. Audit Level 2:
    • Write:
      • SMB2 WRITE
      • SMB2 SET_INFO
      • SMB2 IOCTL
    • Update:
      • SMB2 FLUSH
  3. Audit Level 3:
    • Read access permissions:
      • SMB2 QUERY_INFO (INFO_FILE & INFO SECURITY)
    • Lookup:
      • SMB2 QUERY_DIRECTORY (can use wildcard, pattern a specific filename).
        note

        File lookup can also be performed by sending a SMB2 CREATE request with the filename 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 wildcard, pattern or even filename).
  4. Audit Level 4:
    • Read:
      • SMB2 READ
    • Commits:
      • SMB2 FLUSH
  5. 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​

In this section we'll cover the three factors that determine how audit logging is configured:

  • Audit Logging Enabled/Disabled: A global setting that toggles the 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 that is 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) The path where the audit log files are stored. Each audit log file will have a suffix containing the date of the day for which the log is generated.
  • days=<days>: (optional) The number of days for which the audit log files are retained. Default value: 1.
  • uid=<uid>: (optional) Specifies whether log messages should 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 should 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 should 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 should be handled in log messages. Sensitive data includes domain names, IP addresses, user names and IDs, and file paths. Possible values:
    • allow: All data appears as-is in log messages.
    • strip: Sensitive data is stripped from log messages, and replaced with ***.
    • hash: Sensitive data is hashed in log messages, 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​

This is the first step in configuring audit logging. 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​

Assuming audit logging has been enabled and configured, edit the relevant [share] section for the share you want to configure, set the audit_level parameter to the desired value, similar to the following example:

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

Adding a Share with an Audit Level Using the CLI​

Assuming audit logging has been enabled and configured, you can 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