Skip to main content

Use audit-explain tool


You can use the audit-explain tool to translate the audit messages in the audit log in to an easy-to-read format.

Before you begin
  • You must have specific access permissions.

  • You must have the Passwords.txt file.

  • You must know the IP address of the primary Admin Node.

About this task

The audit-explain tool, available on the primary Admin Node, provides simplified summaries of the audit messages in an audit log.

Important The audit-explain tool is primarily intended for use by technical support during troubleshooting operations. Processing audit-explain queries can consume a large amount of CPU power, which might impact StorageGRID operations.

This example shows typical output from the audit-explain tool. These four SPUT audit messages were generated when the S3 tenant with account ID 92484777680322627870 used S3 PUT requests to create a bucket named "bucket1" and add three objects to that bucket.

SPUT S3 PUT bucket bucket1 account:92484777680322627870 usec:124673
SPUT S3 PUT object bucket1/part1.txt tenant:92484777680322627870  cbid:9DCB157394F99FE5 usec:101485
SPUT S3 PUT object bucket1/part2.txt tenant:92484777680322627870  cbid:3CFBB07AB3D32CA9 usec:102804
SPUT S3 PUT object bucket1/part3.txt tenant:92484777680322627870  cbid:5373D73831ECC743 usec:93874

The audit-explain tool can do the following:

  • Process plain or compressed audit logs. For example:

    audit-explain audit.log

    audit-explain 2019-08-12.txt.gz

  • Process multiple files simultaneously. For example:

    audit-explain audit.log 2019-08-12.txt.gz 2019-08-13.txt.gz

    audit-explain /var/local/audit/export/*

  • Accept input from a pipe, which allows you to filter and preprocess the input using the grep command or other means. For example:

    grep SPUT audit.log | audit-explain

    grep bucket-name audit.log | audit-explain

Because audit logs can be very large and slow to parse, you can save time by filtering parts that you want to look at and running audit-explain on the parts, instead of the entire file.


The audit-explain tool does not accept compressed files as piped input. To process compressed files, provide their file names as command-line arguments, or use the zcat tool to decompress the files first. For example:

zcat audit.log.gz | audit-explain

Use the help (-h) option to see the available options. For example:

$ audit-explain -h

  1. Log in to the primary Admin Node:

    1. Enter the following command: ssh admin@primary_Admin_Node_IP

    2. Enter the password listed in the Passwords.txt file.

    3. Enter the following command to switch to root: su -

    4. Enter the password listed in the Passwords.txt file.

      When you are logged in as root, the prompt changes from $ to #.

  2. Enter the following command, where /var/local/audit/export/audit.log represents the name and the location of the file or files you want to analyze:

    $ audit-explain /var/local/audit/export/audit.log

    The audit-explain tool prints human-readable interpretations of all messages in the specified file or files.

    Note To reduce line lengths and to aid readability, timestamps aren't shown by default. If you want to see the timestamps, use the timestamp (-t) option.