Use the audit log

You can find a history of changes to user accounts, user roles, and more in the audit log. The logs record all incoming CQL command requests and both successful and failed authentication attempts on a node.

You can implement the custom logger and inject it with the class name as a parameter in the cassandra.yaml file.

HCD provides two default loggers:

  • BinAuditLogger: An efficient way to log events to file in a binary format. This is the community-recommended logger for performance reasons.

  • FileAuditLogger: Logs events to the audit/audit.log file using the Simple Logging Facade for Java (SLF4J) logger.

You can view the audit log using the auditlogviewer tool.

Audit log contents

Audit logging captures the following events:

  • Successful and unsuccessful authentication

  • All database commands executed via native CQL protocol attempted or successfully executed

Each audit log implementation accesses the following attributes, and the default text-based logger concatenates these fields with pipes to create the final message.

  • user: User name, if available

  • host: Host IP, where the command is being executed

  • source ip address: Source IP address from where the request initiated

  • source port: Source port number from where the request initiated

  • timestamp: Unix time stamp

  • type: Request type (SELECT, INSERT, and so on)

  • category: Category of the request (DDL, DML, and so on)

  • keyspace: Keyspace where the request is executed, if applicable

  • scope: Table/Aggregate name/ function name/ trigger name etc., as applicable

  • operation: CQL command being executed

Executing prepared statements logs the query as provided by the client in the prepare call, along with the execution timestamp and all other attributes. For more information, see auditlogviewer options. The audit log does not include actual values bound for prepared statement execution.

Configure the AuditLog in the cassandra.yaml file

The cassandra.yaml file has an audit_logging_options section that you can use to configure AuditLog. To use audit logging on one node, either edit that file, or enable and configure using nodetool.

HCD provides the following options for AuditLog:

  • enabled: This option enables/ disables audit log

  • logger: Class name of the logger/ custom logger.

  • audit_logs_dir: Auditlogs directory location, if not set, default to cassandra.logdir.audit or cassandra.logdir
    /audit/

  • included_keyspaces: Comma-separated list of keyspaces to be included in audit log, default - includes all keyspaces

  • excluded_keyspaces: Comma-separated list of keyspaces to be excluded from audit log, default - excludes no keyspace except system, system_schema and system_virtual_schema

  • included_categories: Comma-separated list of Audit Log Categories to be included in audit log, default - includes all categories

  • excluded_categories: Comma-separated list of Audit Log Categories to be excluded from audit log, default - excludes no category

  • included_users: Comma-separated list of users to be included in audit log, default - includes all users

  • excluded_users: Comma-separated list of users to be excluded from audit log, default - excludes no user

List of available categories are: QUERY, DML, DDL, DCL, OTHER, AUTH, ERROR, and PREPARE.

Use nodetool to enable AuditLog

The nodetool enableauditlog command enables AuditLog with the cassandra.yaml file defaults. Those defaults can be overridden using options with this nodetool command.

For example, to enable AuditLog with the default settings, run the following command:

nodetool enableauditlog

Options for nodetool enableauditlog

The following options are supported for nodetool enableauditlog:

Option Description

--excluded-categories

Comma-separated list of audit log categories to be excluded for audit log. If you do not set it, HCD uses the cassandra.yaml value.

--excluded-keyspaces

Comma-separated list of keyspaces to be excluded for audit log. If you do not set it, HCD uses the cassandra.yaml value. Remember that system, system_schema and system_virtual_schema are excluded by default. If you are overwriting these options with nodetool, then you need to add these keyspaces back if you don’t want them in audit logs.

--excluded-users

Comma-separated list of users to be excluded for audit log. If you do not set it, HCD uses the cassandra.yaml value.

--included-categories

Comma-separated list of audit log categories to be included for audit log. If you do not set it, HCD uses the cassandra.yaml value.

--included-keyspaces

Comma-separated list of keyspaces to be included for audit log. If you do not set it, HCD uses the cassandra.yaml value.

--included-users

Comma-separated list of users to be included for audit log. If you do not set it, HCD uses the cassandra.yaml value.

--logger

Logger name to be used for AuditLogging. If you do not set it, HCD uses the cassandra.yaml value. The default is BinAuditLogger.

nodetool command to disable AuditLog

The nodetool disableauditlog command disables AuditLog.

Run the following command to disable AuditLog:

nodetool disableuditlog

nodetool command to reload AuditLog filters

The nodetool enableauditlog command can be used to reload auditlog filters with either defaults or previous loggername and updated filters:

nodetool enableauditlog --loggername DEFAULT_OR_EXISTING_LOGGERNAME --included-keyspaces NEW_FILTER_VALUES

Replace the following:

  • DEFAULT_OR_EXISTING_LOGGERNAME: Default or existing logger name

  • NEW_FILTER_VALUES: New filter values

View the contents of AuditLog files

You can use auditlogviewer to view the contents of the audit binlog file in human-readable text format.

auditlogviewer PATH_1 [PATH_2...PATH_N] [OPTIONS]

Replace the following:

  • PATH_1: Path to the first audit binlog file

  • PATH_2: Path to the second audit binlog file

  • PATH_N: Path to an additional audit binlog file

  • OPTIONS: Options for auditlogviewer

Options for auditlogviewer

HCD supports the following options for auditlogviewer:

Option Description

-f,--follow

Upon reaching the end of the log, continue indefinitely, waiting for more records.

-r,--roll_cycle

How often to roll audit log segments so they can potentially be reclaimed. Available options are: MINUTELY, HOURLY, DAILY, LARGE_DAILY, XLARGE_DAILY, and HUGE_DAILY.

-h,--help

Display help information.

For example, to dump the contents of audit log files to the console, run the following command:

auditlogviewer /logs/cassandra/audit

This command displays the contents of the audit log files in human-readable text format.

LogMessage: user:anonymous|host:localhost/X.X.X.X|source:/X.X.X.X|port:60878|timestamp:1521158923615|type:USE_KS|category:DDL|ks:dev1|operation:USE "dev1"

Configure BinAuditLogger as a logger in AuditLogging

To use BinAuditLogger as a logger in AuditLogging, set the logger to BinAuditLogger in the cassandra.yaml file under the audit_logging_options section.

audit_logging_options:
  enabled: true
  logger: org.apache.cassandra.audit.BinAuditLogger
  audit_logs_dir: /var/log/cassandra/audit

Advanced options for BinAuditLogger

You can further configure BinAuditLogger using its advanced options in the cassandra.yaml file.

The following options are supported for BinAuditLogger:

Option Description

block

Determines whether to block the client thread if the queue is full. The default is set to true.

max_queue_weight

Maximum weight of in-memory queue for records waiting to be written to the audit log file before blocking or dropping the log records. The default is set to 256 * 1024 * 1024.

max_log_size

Maximum size of the rolled files to retain on disk before deleting the oldest file. The default is set to 16L * 1024L * 1024L * 1024L.

roll_cycle

How often to roll audit log segments so they can potentially be reclaimed. Available options are: MINUTELY, HOURLY, DAILY,LARGE_DAILY, XLARGE_DAILY, and HUGE_DAILY. For more options, see net.openhft.chronicle.queue.RollCycles. The default is set to HOURLY.

Configure FileAuditLogger as a logger in AuditLogging

To use FileAuditLogger as a logger in AuditLogging, set the class name in the cassandra.yaml file and configure the audit log events to flow through a separate log file instead of system.log.

<!-- Audit Logging (FileAuditLogger) rolling file appender to audit.log -->
<appender name="AUDIT" class="ch.qos.logback.core.rolling.RollingFileAppender">
  <file>${cassandra.logdir}/audit/audit.log</file>
  <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
    <!-- rollover daily -->
    <fileNamePattern>${cassandra.logdir}/audit/audit.log.%d{yyyy-MM-dd}.%i.zip</fileNamePattern>
    <!-- each file should be at most 50MB, keep 30 days worth of history, but at most 5GB -->
    <maxFileSize>50MB</maxFileSize>
    <maxHistory>30</maxHistory>
    <totalSizeCap>5GB</totalSizeCap>
  </rollingPolicy>
  <encoder>
    <pattern>%-5level [%thread] %date{ISO8601} %F:%L - %msg%n</pattern>
  </encoder>
</appender>

<!-- Audit Logging additivity to redirect audit logging events to audit/audit.log -->
<logger name="org.apache.cassandra.audit" additivity="false" level="INFO">
    <appender-ref ref="AUDIT"/>
</logger>

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2024 DataStax | Privacy policy | Terms of use

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: +1 (650) 389-6000, info@datastax.com